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Preface 


Intended Audience 

This manual is intended for programmers who want to invoke and use the 
functions provided by OpenVMS utilities. 

Document Structure 

This document contains the following chapters. 

Chapter 1 introduces the utility routines and describes the documentation format 
used to describe each set of utility routines, as well as the individual routines 
in each set. Each subsequent chapter contains an introduction to a set of utility 
routines, a programming example to illustrate the use of the routines in the set, 
and a detailed description of each routine. 

This manual presents the utility routine sets as follows: 

• Chapter 2 — ACL editor routine 

• Chapter 3 — CLI routines 

• Chapter 4 — CONVERT routines 

• Chapter 5 — DCX routines 

• Chapter 6 — DECTPU routines 

• Chapter 7 — EDT routines 

• Chapter 8 — FDL routines 

• Chapter 9 — LBR routines 

• Chapter 10 — MAIL routines 

• Chapter 11 — NCS routines 

• Chapter 12 — PSM routines 

• Chapter 13 — SMB routines 

• Chapter 14 — SOR routines 

Associated Documents 

OpenVMS Programming Interfaces: Calling a System Routine contains useful 
information for all programmers and describes in detail the documentation format 
of the routine descriptions. 

Some sets of utility routines documented in this manual invoke and manipulate 
utilities that have a command-level interface. Consult the following manuals for 
a description of the command-level interface: 

• OpenVMS National Character Set Utility Manual 


xiii 




• OpenVMS System Manager's Manual 

• OpenVMS Command Definition, Librarian, and Message Utilities Manual 

• OpenVMS Record Management Utilities Reference Manual 

• OpenVMS EDT Reference Manual 

• OpenVMS User*s Manual 

• DEC Text Processing Utility Reference Manual 

Conventions 

In this manual, every use of OpenVMS AXP means the OpenVMS AXP operating 
system, every use of OpenVMS VAX means the OpenVMS VAX operating system, 
and every use of OpenVMS means both the OpenVMS AXP operating system and 
the OpenVMS VAX operating system. 

The following conventions are used to identify information specific to OpenVMS 
AXP or to OpenVMS VAX: 



The VAX icon denotes the beginning of information 
specific to OpenVMS VAX. 

♦ 

The diamond symbol denotes the end of a section of 
information specific to OpenVMS AXP or to OpenVMS 
VAX. 

The following conventions are also used in this manual: 

Ctrl/* 

A sequence such as CtrVx indicates that you must hold down 
the key labeled Ctrl while you press another key or a pointing 
device button. 


A horizontal ellipsis in examples indicates one of the following 
possibilities: 


• Additional optional arguments in a statement have been 
omitted. 


• The preceding item or items can be repeated one or more 
times. 


• Additional parameters, values, or other information can be 
entered. 


A vertical ellipsis indicates the omission of items from a code 
example or command format; the items are omitted because 
they are not important to the topic being discussed. 

( ) 

In format descriptions, parentheses indicate that, if you 
choose more than one option, you must enclose the choices 
in parentheses. 

[] 

In format descriptions, brackets indicate optional elements. 

You can choose one, none, or all of the options. (Brackets are 
not optional, however, in the syntax of a directory name in 
an OpenVMS file specification, or in the syntax of a substring 
specification in an assignment statement.) 

1 } 

In format descriptions, braces surround a required choice of 
options; you must choose one of the options listed. 


XIV 


boldface text 


italic text 


UPPERCASE TEXT 


numbers 


Boldface text represents the introduction of a new term or the 
name of an argument, an attribute, or a reason. 

Boldface text is also used to show user input in Bookreader 
versions of the manual. 

Italic text emphasizes important information, indicates 
variables, and indicates complete titles of manuals. Italic 
text also represents information that can vary in system 
messages (for example. Internal error number), command lines 
(for example, /PRODUCER=na7ne), and command parameters 
in text. 

Uppercase text indicates a command, the name of a routine, 
the name of a file, or the abbreviation for a system privilege. 

A hyphen in code examples indicates that additional 
arguments to the request are provided on the line that follows. 

All numbers in text are assumed to be decimal, unless 
otherwise noted. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 


XV 




_ 1 

Introduction to Utility Routines 


A set of utility routines performs a particular task or set of tasks. For example, 
you can use the Print Symbiont Modification (PSM) routines to modify the print 
symbiont, and the EDT routines to invoke the EDT editor from a program. 

Some of the tasks performed by utility routines can also be performed at the 
Digital Command Language (DCL) level (for example, the DCL command EDIT 
invokes the EVE editor). While DCL commands invoke utilities that let you 
perform tasks at your terminal, you can perform some of these tasks at the 
programming level through the use of the utility routines. 

When using a set of utility routines that performs the same tasks as the related 
utility, you should read the documentation for that utility; doing so will provide 
additional information about the tasks the routines can perform as a set. The 
following table lists utilities and their corresponding routines: 


Utility or Editor 

Utility Routines 

Access control list editor 

ACL Editor routine 

Command Definition utility 

CLI routines 

Convert and Convert/Reclaim utilities 

CONVERTroutines 

EDT editor 

EDT routines 

DEC Text Processing Utility 

DECTPU routines 

File Definition Language facility 

FDL routines 

Librarian utility 

LBR routines 

Mail utility 

MAIL routines 

National Character Set utility 

NCS routines 

Sort/Merge utility 

SOR routines 

When a set of utility routines performs functions that you cannot perform 
by invoking a utility, the functions provided by that set of routines is termed 
a facility. The following facilities have no other user interface except the 
programming interface provided by the utility routines described in this manual: 

Facility 

Utility Routines 

Data Compression/Expansion facility 

DCX routines 

Print Symbiont Modification facility 

PSM routines 

Symbiont/Job Controller Interface facility 

SMB routines 


Like all other system routines in the OpenVMS environment, the utility routines 
described in this manual conform to the OpenVMS Calling Standard. Note that 
for stylistic purposes, the calling syntax illustrated for routines documented 
in this manual is consistent. However, you should consult your language 
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documentation to determine the appropriate syntax for calling these routines 
from your programming language. 

Each chapter of this book documents one set of utility routines. Each chapter has 
the following major components, documented as a major heading: 

• An introduction to the set of utility routines. This component discusses the 
utility routines as a group and explains how to use them. 

• A series of descriptions of each utility routine in the set. 

Most of the chapters also include a programming example that illustrates how 
the utility routines are used. 
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This chapter describes the access control list editor (ACL editor) routine, 
ACLEDIT$EDIT. User-written applications can use this callable interface of the 
ACL editor to manipulate access control lists (ACLs). 

The ACL editor is a utility that lets you create and maintain access control lists. 
Using ACLs, you can fine-tune access to the protected objects available to system 
users and listed as follows: 

Devices 

Files 

Group global sections 
Logical name tables 
System global sections 
On VAX systems, you can also fine-tune access to the following objects: 
Capabilities 

Common event fiag clusters 
Queues 

Resource domains 
Security classes 
Volumes ♦ 


Currently, the ACL editor provides one callable interface that allows the 
application program to define an object for editing. 

Note that the application program should declare referenced constants and return 
status symbols as external symbols; these symbols will be resolved upon linking 
with the utility shareable image. 

See the OpenVMS Programming Concepts Manual for fundamental conceptual 
information on the creation, translation, and maintenance of access control 
entries (ACEs). 
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2.1 Using the ACL Editor Routine: An Example 

Example 2—1 shows a VAX BLISS program that calls the ACL editor routine. 


Example 2-1 Calling the ACL Editor with a VAX BLISS Program 

MODULE MAIN (LANGUAGE (BLISS32), MAIN = STARTUP) = 

BEGIN 

LIBRARY 'SYS$LIBRARY:LIB'; 

ROUTINE STARTUP = 

BEGIN 

LOCAL 

STATUS, ! Routine return status 

ITMLST : BLOCKVECTOR [6, ITM$S_ITEM, BYTE]; 

! ACL editor item list 

EXTERNAL LITERAL 
ACLEDIT$V_JOURNAL, 

ACLEDIT$V_PROMPT_MODE, 

ACLEDIT$C_OBJNAM, 

ACLEDIT$C_OBJTYP, 

ACLEDIT$C_OPTIONS; 

EXTERNAL ROUTINE 

ACLEDIT$EDIT : ADDRESSING_MODE (GENERAL), ! Main routine 

CLI$GET_VALUE, ! Get qualifier value 
CLI$PRESENT, ! See if qualifier present 
LIB$PUT_OUTPUT, ! General output routine 
STR$COPY_DX; ! Copy string by descriptor 

! Set up the item list to pass baclc to TPU so it can figure out what to do. 

CH$FILL (0, 6*ITM$S_ITEM, ITMLST); 

ITMLST]0, ITM$W_ITMCOD] = ACLEDIT$C_OBJNAM; 

ITMLST[0, ITM$W_BUFSIZ] = %CHARCOUNT ('YOUR_OBJECT_NAME'); 

ITMLST]0, ITM$L_BUFADR] = $DESCRIPTOR ('YOUR_OBJECT_NAME'); 

ITMLST]!, ITM$W_ITMCOD] = ACLEDIT$C_OBJTYP; 

ITMLST]!, ITM$W_BUFSIZ] = 4; 

ITMLST]!, ITM$L_BUFADR] = UPLIT (ACL$C_FILE); 

ITMLST]2, ITM$W_ITMCOD] = ACLEDIT$C_OPTIONS; 

ITMLST]2, ITM$W_BUFSIZ] = 4; 

ITMLST]2, ITM$L_BUFADR] = UPLIT (! ^ ACLEDIT$V_PROMPT_MODE OR 
! " ACLEDIT$V_JOURNAL); 

RETURN ACLEDIT$EDIT (ITMLST); 

END; ! End of routine STARTUP 

END 

ELUDOM 


2.2 ACL Editor Routine 

The following pages describe the ACL editor routine. 


ACL-2 



Access Control List (ACL) Editor Routine 

ACLEDIT$EDIT 


ACLEDIT$EDIT—Edit Access Control List 

The ACLEDIT$EDIT routine is used to create and modify an access control list 
(ACL) associated with any protected object. 

Format 

ACLEDIT$EDIT itemjist 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

itemjist 

OpenVMS usage itemjist_3 
type longword (unsigned) 

access read only 

mechanism by descriptor 

Item list used by the callable ACL editor. The itemjist argument is the address 
of one or more descriptors of arrays, routines, or longword bit masks that control 
various aspects of the editing session. 

Each entry in an item list is in the standard format shown in the following figure: 

Item Code Buffer Length 
Buffer Address 
Return Length Address 

ZK-5012-GE 

The following table provides a detailed description of each item list entry: 

Item Identifier Description 

ACLEDIT$C_OBJNAM Specifies the name of the object whose ACL is being edited. 

tACLEDIT$C_OBJTYP A longword value that specifies the object type code for the type 

or class of the object whose ACL is being edited. These type 
codes are defined in $ACLDEF. The default object type is FILE 
(ACL$C_FILE). 

tAXP specific 
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Item Identifier Description 

ACLEDIT$C_OPTIONS Represents a longword bit mask of the various options available 

to control the editing session. 


Flag 

Function 

ACLEDIT$V_JOURNAL 

Indicates that the editing 
session is to be journaled. 

ACLEDIT$V_RECOVER 

Indicates that the editing 
session is to be recovered from 
an existing journal file. 

acledit$v_keep_recover 

Indicates that the journal file 
used to recover the editing 
session is not to be deleted 
when the recovery is complete. 

ACLEDIT$V_KEEP_JOURNAL 

Indicates that the journal file 
used for the editing session 
is not to be deleted when the 
session ends. 

ACLEDIT$V_PROMPT_MODE 

Indicates that the session is to 
use automatic text insertion 
(prompting) to build new 
access control list entries 
(ACEs). 


ACLEDIT$C_BIT_TABLE Specifies a vector of 32 quadword string descriptors of strings that 

define the names of the bits present in the access mask. (The first 
descriptor defines the name of Bit 0; the last descriptor defines 
the name of Bit 31.) These descriptors are used in parsing or 
formatting an ACE. The buffer address field of the item descriptor 
contains the address of this vector. 
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ACLEDiT$EDIT 

Item Identifier Description 

tACLEDIT$C_CLSNAM A string descriptor that points to the class name of the object 

whose ACL is being modified. The following are valid class 
names: 

• CAPABILITY 

• COMMON_EVENT_FLAG_CLUSTER 

• DEVICE 

• FILE 

• GROUP_GLOBAL_SECTION 

• LOGICAL_NAME_TABLE 

• QUEUE 

• RESOURCE_DOMAIN 

• SECURITY.CLASS 

• SYSTEM_GLOBAL_SECTION 

• VOLUME 

If both OBJTYP and CLSNAM are omitted, the object is assumed 
to belong to the FILE class. 

tVAX specific 

Description 

You use the ACLEDIT$EDIT routine to create and modify an ACL associated 
with any security object. 

Under normal circumstances, the application calls the ACL editor to modify an 
object’s ACL, and control is returned to the application when you finish or abort 
the editing session. 

If you also want to use a customized version of the ACL editor section file, the 
logical name ACLEDT$SECTION should be defined. See the OpenVMS System 
Management Utilities Reference Manual for more information. 

Condition Vaiues Returned 

SS$_NORMAL Normal successful completion. 

RMS$_xxx See the OpenVMS Record Management Services 

Reference Manual for a description of OpenVMS 
RMS status codes. 

TPU$_xxx See Chapter 6 for a description of the TPU- 

specific condition values that may be returned by 
ACLEDIT$EDIT. 
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You use the CLI routines to process command strings using information from a 
command table. A command table contains command definitions that describe 
the allowable formats for commands. To create or modify a command table, 
you must write a command definition file and then process this file with the 
Command Definition utility (the SET COMMAND command). For information 
about how to use the Command Definition utility, see the OpenVMS Command 
Definition, Librarian, and Message Utilities Manual, 

3.1 Introduction to CLI Routines 

The CLI routines include the following: 

• CLI$DCL_PARSE 

• CLI$DISPATCH 

• CLI$GET_VALUE 

• CLI$PRESENT 

When you use the Command Definition utility to add a new command to your 
process command table or to the DCL command table, use the CLI$PRESENT 
and CLI$GET_VALUE routines in the program invoked by the new command. 
These routines retrieve information about the command string that invokes the 
program. 

When you use the Command Definition utility to create an object module 
containing a command table and you link this module with a program, you must 
use all four CLI routines. First, use CLI$DCL_PARSE and CLI$DISPATCH 
to parse command strings and invoke routines. Then, use CLI$PRESENT and 
CLI$GET_VALUE within the routines that execute each command. 

Note that the application program should declare referenced constants and return 
status symbols as external symbols; these symbols are resolved upon linking with 
utility shareable image. 

A CLI must be present in order to use the CLI routines. If your application 
can be run from a detached process, the application should first verify that a 
CLI exists. For information about how to verify that a CLI exists for a process, 
see the description of the SYS$GETJPI system service in the OpenVMS System 
Services Reference Manual. 
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3.2 Using the CLI Routines: An Example 

Example 3—1 contains a command definition file (SUBCOMMANDS.CLD) and 
a FORTRAN program (INCOME.FOR). INCOME.FOR uses the command 
definitions in SUBCOMMANDS.CLD to process commands. To execute the 
example, enter the following commands: 

$ SET COMMAND SUBCOMMANDS/OBJECT=SUBCOMMANDS 
$ FORTRAN INCOME 
$ LINK INCOME,SUBCOMMANDS 
$ RUN INCOME 

INCOME.FOR accepts a command string and parses it using CLI$DCL_PARSE. 
If the command string is valid, the program uses CLI$DISPATCH to execute the 
command. Each routine uses CLI$PRESENT and CLI$GET_VALUE to obtain 
information about the command string. 


Example 3-1 Using the CLI Routines to Retrieve Information About Command 
Lines in a FORTRAN Program 

**************************************************** 

SUBCOMMANDS.CLD 

★*************************************************** 

MODULE INCOME^SUBCOMMANDS 

DEFINE VERB ENTER 
ROUTINE ENTER 

DEFINE VERB FIX 
ROUTINE FIX 

QUALIFIER HOUSE_NUMBERS, VALUE (LIST) 

DEFINE VERB REPORT 
ROUTINE REPORT 

QUALIFIER OUTPUT, VALUE (TYPE = $FILE, 

DEFAULT = "INCOME.RPT") 

DEFAULT 

fir*************************************************** 

INCOME.FOR 

PROGRAM INCOME 
INTEGER STATUS, 

2 CLI$DCL__PARSE, 

2 CLI$DISPATCH 

INCLUDE '($RMSDEF)' 

INCLUDE '($STSDEF)' 

EXTERNAL INCOME_SUBCOMMANDS, 

2 LIB$GET__INPUT 


(continued on next page) 
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Example 3-1 (Cent.) Using the CLI Routines to Retrieve Information About 
Command Lines in a FORTRAN Program 


! Write explanatory text 
STATUS = LIB$PUT_OUTPUT 
2 ('Subcommands: ENTER - FIX - REPORT') 

IF {.NOT. STATUS) CALL LIB$SIGNAL {%VAL (STATUS)) 

STATUS = LIB$PUT_OUTPUT 
2 {'Press CTRL/Z to exit') 

IF (.NOT. STATUS) CALL LIB$SIGNAL {%VAL (STATUS)) 

! Get first subcommand 

STATUS = CLI$DCL_PARSE {%VAL (0), 

2 INCOME_SUBCOMMANDS, ! CLD module 

2 LIB$GET_INPUT, 

2 LIB$GET_INPUT, 

2 'INCOME> ') 

! Do it until user presses CTRL/Z 
DO WHILE (STATUS .NE. RMS$_EOF) 

! If no error on dcl_parse 
IF (STATUS) THEN 

! Dispatch depending on subcommand 
STATUS = CLI$DISPATCH () 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Do not signal warning again 

ELSE IF (IBITS (STATUS, 0, 3) .NE. STS$K_WARNING) THEN 
CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 


! Parameter routine 
! Command routine 
! Command prompt 


! Get another subcommand 
STATUS = CLI$DCL_PARSE (%VAL (0), 

2 INCOME_SUBCOMMANDS, 

2 LIB$GET_INPUT, 

2 LIB$GET_INPUT, 

2 'INC0ME> ') 

END DO 
END 


! CLD module 
1 Parameter routine 
! Command routine 
! Command prompt 


INTEGER FUNCTION ENTER () 
INCLUDE '($SSDEF)' 

TYPE *, 'ENTER invoked' 
ENTER = SS$_NORMAL 
END 


INTEGER FUNCTION FIX () 

INTEGER STATUS, 

2 CLI$PRESENT, 

2 CLI$GET_VALUE 

CHARACTER*15 HOUSE_NUMBER 
INTEGER*2 HN_SIZE 
INCLUDE '($SSDEF)' 

EXTERNAL CLI$ ABSENT 
TYPE *, 'FIX Invoked' 

! If user types /house_numbers=(n,...) 

IF (CLI$PRESENT ('HOUSE_NUMBERS')) THEN 
! Get first value for /house_numbers 
STATUS = CLI$GET_VALUE {'HOUSE_NUMBERS', 
2 HOUSE_NUMBER, 

2 HN_SIZE) 


(continued on next page) 
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Example 3-1 (Cont.) Using the CLI Routines to Retrieve information About 
Command Lines in a FORTRAN Program 

! Do it until the list is depleted 
DO WHILE (STATUS) 

TYPE *, 'House number = HOUSE_NUMBER (1:HN_SIZE) 

STATUS = CLI$GET_VALUE ('HOUSE_NUMBERS', 

2 HOUSE_NUMBER, 

2 HN_SIZE) 

END DO 

! Malce sure termination status was correct 
IF (STATUS .NE. %LOC (CLI$_ABSENT)) THEN 
CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 
END IF 

FIX = SS$_NORMAL 
END 

INTEGER FUNCTION REPORT () 

INTEGER STATUS, 

2 CLI$GET_VALUE 

CHARACTER*64 FILENAME 
INTEGER*2 FN_SIZE 
INCLUDE '($SSDEF)' 

TYPE *, 'REPORT entered' 

! Get value for /output 

STATUS = CLI$GET_VALUE ('OUTPUT', 

2 FILENAME, 

2 FN SIZE) 

IF (.NOT. STATUS) CALL LIBfSIGNAL (%VAL (STATUS)) 

TYPE *, 'Output file: ', FILENAME (1:FN_SIZE) 

REPORT = SS$_NORMAL 
END 


3.3 CLI Routines 

The following pages describe the individual CLI routines. 
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CLI$DCL_PARSE—Parse DCL Command String 

The CLI$DCL_PARSE routine supplies a command string to DCL for parsing. 
DCL separates the command string into its individual elements according to the 
syntax specified in the command table. 


Format 


CLI$DCL_PARSE [command_string] ,table [,param_routine] [,prompt_routine] 
[,pronnpt_string] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

command_string 

OpenVMS usage char_string 

type character string 

access read only 

mechanism by descriptor—fixed length 

Character string containing the command to be parsed. The command_string 
argument is the address of a descriptor specifying the command string to be 
parsed. If the command string includes a comment (delimited by an exclamation 
mark), DCL ignores the comment. 

If the command string contains a hyphen to indicate that the string is being 
continued, DCL uses the routine specified in the prompt__routine argument to 
obtain the rest of the string. The command string is limited to 256 characters. 
However, if the string is continued with a hyphen, CLI$DCL_PARSE can prompt 
for additional input until the total number of characters is 1024. 

If you specify the command_string argument as zero and specify a prompt 
routine, then DCL prompts for the entire command string. However, if you 
specify the command_string argument as zero and also specify the prompt., 
routine argument as zero, then DCL restores the parse state of the command 
string that originally invoked the image. 

CLI$DCL_PARSE does not perform DCL-style symbol substitution on the 
command string. 


table 

OpenVMS usage 

type 

access 

mechanism 


address 
address 
read only 
by value 
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Address of the compiled command tables to be used for command parsing. The 
command tables are compiled separately by the Command Definition utility using 
the DCL command SET COMMAND/OBJECT and are then linked with your 
program. A global symbol is defined by the Command Definition utility that 
provides the address of the tables. The global symbol’s name is taken from the 
module name given on the MODULE statement in the command definition file, or 
from the file name if no MODULE statement is present. 

param_routine 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by reference 

Name of a routine to obtain a required parameter not supplied in the command 
text. The param_routine argument is the address of a routine containing a 
required parameter that was not specified in the command_string argument. 

To specify the parameter routine, use the address of LIB$GETJNPUT or the 
address of a routine of your own that has the same three-argument calling 
format as LIB$GET_INPUT. See the description of LIB$GET_INPUT in the 
OpenVMS RTL Library (LIB$) Manual for information about the calling format. 
If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates the error 
status outward or signals RMS$_EOF in the cases listed in the “Description” 
section. 

You can obtain the prompt string for a required parameter from the command 
table specified in the table argument. 

prompt_routine 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by reference 

Name of a routine to obtain all or part of the text of a command. The prompt_ 
routine argument is the address of a routine to obtain the text or the remaining 
text of the command depending on the command_string argument. If you 
specify a zero in the command_string argument, DCL uses this routine to 
obtain an entire command line. DCL uses this routine to obtain a continued 
command line if the command string (obtained from the command_string 
argument) contains a hyphen to indicate that the string is being continued. 

To specify the prompt routine, use the address of LIB$GET_INPUT or the 
address of a routine of your own that has the same three-argument calling format 
as LIB$GET_INPUT. See the description of LIB$GET_INPUT in the OpenVMS 
RTL Library (LIB$) Manual for information about the calling format. 

If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates the error 
status outward or signals RMS$_EOF in the cases listed in the “Description” 
section. 

prompt_string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 
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Character string containing a prompt. The prompt_string argument is the 
address of a string descriptor pointing to the prompt string to be passed as the 
second argument to the prompt_routine argument. 

If DCL is using the prompt routine to obtain a continuation line, DCL inserts 
an underscore character before the first character of the prompt string to create 
the continuation prompt. If DCL is using the prompt routine to obtain an entire 
command line (that is, a zero was specified as the command_string argument), 
DCL uses the prompt string exactly as specified. 

The prompt string is limited to 32 characters. The string COMMAND> is the 
default prompt string. 


Description 

The CLI$DCL_PARSE routine supplies a command string to DCL for parsing. 
DCL parses the command string according to the syntax in the command table 
specified in the table argument. 

The CLI$DCL_PARSE routine can prompt for required parameters if you specify 
a parameter routine in the routine call. In addition, the CLI$DCL_PARSE 
routine can prompt for entire or continued command lines if you supply the 
address of a prompt routine. 

If you do not specify a command string to parse and the user enters a null 
string in response to the DCL prompt for a command string, CLI$DCL_PARSE 
immediately terminates and returns the status RMS$_EOF. 

If DCL prompts for a required parameter and the user enters CTRL/Z, CLI$DCL_ 
PARSE immediately terminates and returns the status CLI$_NOCMD, regardless 
of whether you specify or do not specify a command string to parse. If DCL 
prompts for a parameter that is not required and the user enters CTRL/Z, 
CLI$DCL_PARSE returns the status CLI$_NORMAL. 

Whenever CLI$DCL_PARSE encounters an error, it both signals and returns the 
error. 


Condition Values Returned 

CLI$IWERB 

CLI$_NORMAL 

CLI$_NOCOMD 


RMS$_EOF 


CLI$_INVREQTYP 


Invalid or missing verb. 

Normal successful completion. 

Routine terminated. You entered a null string in 
response to a prompt from the prompt_routine 
argument, causing the CLI$DCL_PARSE routine 
to terminate. 

Routine terminated. You pressed CTRL/Z in 
response to a prompt, causing the CLI$DCL_ 
PARSE routine to terminate. 

Calling process did not have a CLI to perform 
this function, or the CLI did not support the 
request. 
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CLI$DISPATCH—Dispatch to Action Routine 

The CLI$DISPATCH routine invokes the subroutine associated with the verb 
most recently parsed by a CLI$DCL_PARSE routine call. 

Format 

CLI$DISPATCH [userarg] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under CONDITION 
VALUE RETURNED. 

Argument 

userarg 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 

Data to be passed to the action routine. The userarg argument is a longword 
that contains the data to be passed to the action routine. This data can be used 
in any way you want. 

Description 

The CLI$DISPATCH routine invokes the subroutine associated with the verb 
most recently parsed by a CLI$DCL_PARSE routine call. If the routine is 
successfully invoked, the return status is the status returned by the action 
routine. Otherwise, a status of CLI$_INVROUT is returned. 

Condition Value Returned 

CLI$_INVROUT CLI$DISPATCH unable to invoke the routine. 

An invalid routine is specified in the command 
table, or no routine is specified. 

CLI$_INVREQTYP Calling process did not have a CLI to perform 

this function or the CLI did not support the 
request. 
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CLI$GET_VALUE—Get Value of Entity in Command String 

The CLI$GET_VALUE routine retrieves a value associated with a specified 
qualifier, parameter, keyword, or keyword path from the parsed command string. 


Format 


CLI$GET_VALUE entity_desc ,retdesc [,retlength] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

entity_desc 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Character string containing the label (or name if no label is defined) of the entity. 
The entity_desc argument is the address of a string descriptor that points to an 
entity that may appear on a command line. The entity^desc argument can be 
expressed as one of the following: 

• A parameter, qualifier, or keyword name or label 

• A keyword path 

The entity_desc argument can contain qualifier, parameter, or keyword names, 
or can contain labels that were assigned with the LABEL clause in the command 
definition file. If you used the LABEL clause to assign a label to an entity, you 
must specify the label in the entity_desc argument. Otherwise, use the name of 
the entity. 

You use a keyword path to reference keywords used as values of parameters, 
qualifiers, or other keywords. A keyword path contains a list of entity names or 
labels separated by periods. If the LABEL clause was used to assign a label to an 
entity, you must specify the label in the keyword path. Otherwise, you must use 
the name of the entity. 

The following command string illustrates a situation where keyword paths 
are needed to uniquely identify keywords. In this command string, you can 
use the same keywords with more than one qualifier. (This is defined in the 
command definition file by having two qualifiers refer to the same DEFINE TYPE 
statement.) 

$ NEWC0MMAND/QUAL1=(START=5,END=10)/QUAL2=(START=2,END=5) 
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The keyword path QUALl.START identifies the START keyword when it is 
used with QUALl; the keyword path QUAL2.START identifies the ke 5 rword 
START when it is used with QUAL2. Because the name START is an ambiguous 
reference if used alone, the keywords QUALl and QUAL2 are needed to resolve 
the ambiguity. 

You can omit keywords from the beginning of a keyword path if they are not 
needed to unambiguously resolve a keyword reference. A keyword path can be no 
more than eight names long. 

If you use an ambiguous keyword reference, DCL resolves the reference by 
checking, in the following order: 

1. The parameters in your command definition file, in the order they are listed 

2. The qualifiers in your command definition file, in the order they are listed 

3. The keyword paths for each parameter, in the order the parameters are listed 

4. The keyword paths for each qualifier, in the order the qualifiers are listed 

DCL uses the first occurrence of the entity as the keyword path. Note that DCL 
does not issue an error message if you provide an ambiguous keyword. However, 
because the keyword search order may change in future releases of VMS, you 
should never use ambiguous ke 3 rword references. 

If the entity_desc argument does not exist in the command table, CLI$GET_ 
VALUE signals a syntax error (by means of the signaling mechanism described in 
the OpenVMS Programming Concepts Manual). 

retdesc 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Character string containing the value retrieved by CLI$GET_VALUE. The 
retdesc argument is the address of a string descriptor pointing to the buffer to 
receive the string value retrieved by CLI$GET_VALUE. The string is returned 
using the STR$COPY_DX Run-Time Library routine. 

If there are errors in the specification of the return descriptor or in copying the 
results using that descriptor, the STR$COPY_DX routine will signal the errors. 
For a list of these errors, see the OpenVMS RTL String Manipulation (STR$) 
Manual. 

retlength 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Word containing the number of characters DCL returns to retdesc. The 
retlength argument is the address of the word containing the length of the 
retrieved value. 
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Description 

The CLI$GET_VALUE routine retrieves a value associated with a specified 
qualifier, parameter, keyword, or keyword path from the parsed command string. 

You can use the following label names with CLI$GET_VALUE to retrieve special 
strings: 

$VERB Describes the verb in the command string (the first four letters of the 
spelling as defined in the command table, instead of the string that 
was actually typed). 

$LINE Describes the entire command string as stored internally by DCL. 

In the internal representation of the command string, multiple 
spaces and tabs are removed, alphabetic characters are converted 
to uppercase, and comments are stripped. Integers are converted 
to decimal. If dates and times are specified in the command string, 
DCL fills in any defaulted fields. Also, if date-time strings (such as 
YESTERDAY) are used, DCL substitutes the corresponding absolute 
time value. 

To obtain the values for a list of entities, call CLI$GET_VALUE repeatedly 
until all values have been returned. After each CLI$GET_VALUE call, the 
returned condition value indicates whether there are more values to be obtained. 
You should call CLI$GET_VALUE until you receive a condition value of CLI$_ 
ABSENT. 

When you are using CLI$GET_VALUE to obtain a list of qualifier or keyword 
values, you should get all values in the list before starting to parse the next 
entity. 


Condition Values Returned 

CLI$_COMMA 

CLI$_CONCAT 

SS$_NORMAL 

CLI$_ABSENT 

CLI$_INVREQTYP 


Returned value terminated by a comma. This 
shows there are additional values in the list. 

Returned value concatenated to the next value 
with a plus sign. This shows there are additional 
values in the list. 

Returned value terminated by a blank or an 
end-of-line. This shows that the value is the last, 
or only, value in the list. 

No value returned. The value is not present, or 
the last value in the list was already returned. 

Calling process did not have a CLI to perform 
this function or the CLI did not support the 
request. 
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CLI$PRESENT—Determine Presence of Entity in Command String 

The CLI$PRESENT routine examines the parsed command string to determine 
whether the entity referred to by the entity_desc argument is present. 


Format 

CLI$PRESENT entity_desc 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under CONDITION 
VALUES RETURNED. 

Argument 

entity_desc 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Character string containing the label (or name if no label is defined) of the entity. 
The entity_desc argument is the address of a string descriptor that points to an 
entity that may appear on a command line. An entity can be expressed as one of 
the following: 

• A parameter, qualifier, or keyword name or label 

• A keyword path 

A keyword path is used to reference keywords that are accepted by parameters, 
qualifiers, or other keywords. A ke 3 rword path contains a list of entity names 
separated by periods. See the description of the entity_desc argument in the 
CLI$GET_VALUE routine for more information about specifying keyword paths 
as arguments for CLI routines. 

The entity_desc argument can contain parameter, qualifier, or keyword names, 
or can contain labels that were assigned with the LABEL clause in the command 
definition file. If the LABEL clause was used to assign a label to a qualifier, 
parameter, or keyword, you must specify the label in the entity_desc argument. 
Otherwise, you must use the actual name of the qualifier, parameter, or keyword. 

If the entity_desc argument does not exist in the command table, 
CLI$PRESENT signals a syntax error (by means of the signaling mechanism 
described in the OpenVMS Programming Concepts Manual). 
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Description 

The CLI$PRESENT routine examines the parsed command string to determine 
whether the entity referred to by the entity_desc argument is present. 

When CLI$PRESENT tests whether a qualifier is present, the condition value 
indicates whether the qualifier is used globally or locally. You can use a global 
qualifier anywhere in the command line; you use a local qualifier only after 
a parameter. A global qualifier is defined in the command definition file with 
PLACEMENT=GLOBAL; a local qualifier is defined with PLACEMENT=LOCAL. 

When you test for the presence of a global qualifier, CLI$PRESENT determines 
if the qualifier is present anywhere in the command string. If the qualifier 
is present in its positive form, CLI$PRESENT returns CLI$_PRESENT; if 
the qualifier is present in its negative form, CLI$PRESENT returns CLI$_ 
NEGATED. 

You can test for the presence of a local qualifier when you are parsing parameters 
that can be followed by qualifiers. After you call CLI$GET_VALUE to fetch the 
parameter value, call CLI$PRESENT to determine whether the local qualifier 
is present. If the local qualifier is present in its positive form, CLI$PRESENT 
returns CLI$_LOCPRES; if the local qualifier is present in its negative form, 
CLI$PRESENT returns CLI$_LOCNEG. 

A positional qualifier affects the entire command line if it appears after the verb 
but before the first parameter. A positional qualifier affects a single parameter 
if it appears after a parameter. A positional qualifier is defined in the command 
definition file with the PLACEMENT=POSITIONAL clause. 

To determine whether a positional qualifier is used globally, call CLI$PRESENT 
to test for the qualifier before you call CLI$GET_VALUE to fetch any parameter 
values. If the positional qualifier is used globally, CLI$PRESENT returns either 
CLI$_PRESENT or CLI$_NEGATED. 

To determine whether a positional qualifier is used locally, call CLI$PRESENT 
immediately after a parameter value has been fetched by CLI$GET_VALUE. The 
most recent CLI$GET_VALUE call to fetch a parameter defines the context for a 
qualifier search. Therefore, CLI$PRESENT tests whether a positional qualifier 
was specified after the parameter that was fetched by the most recent CLI$GET_ 
VALUE call. If the positional qualifier is used locally, CLI$PRESENT returns 
either CLI$_LOCPRES or CLI$_LOCNEG. 

Condition Values Returned 

CLI$_PRESENT Specified entity present in the command string. 

This status is returned for all entities except 
local qualifiers and positional qualifiers that are 
used locally. 

CLI$_NEGATED Specified qualifier present in negated form (with 

/NO) and used as a global qualifier. 
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CLI$_LOCPRES 

CLI$_LOCNEG 

CLI$_DEFAULTED 

CLI$_ABSENT 

CLI$_INVREQTYP 


Specified qualifier present and used as a local 
qualifier. 

Specified qualifier present in negated form (with 
/NO) and used as a local qualifier. 

Specified entity not present, but it is present by 
default. 

Specified entity not present, and it is not present 
by default. 

Calling process did not have a CLI to perform 
this function, or the CLI did not support the 
request. 
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This chapter describes the CONVERT routines. These routines perform the 
functions of both the Convert and Convert/Reclaim utilities. 

4.1 Introduction to CONVERT Routines 

The Convert utility copies records from one or more files to an output file, 
changing the record format and file organization to that of the output file. You 
can invoke the functions of the Convert utility from within a program by calling 
the following series of three routines, in this order: 

1. CONV$PASS_FILES 

2. CONV$PASS_OPTIONS 

3. CONV$CONVERT 

Note that the application program should declare referenced constants and return 
status symbols as external symbols; these symbols are resolved upon linking with 
utility shareable image. Note too, that FDL errors may be returned to the calling 
program where applicable. 

The Convert/Reclaim utility reclaims empty buckets in Prolog 3 indexed files so 
that new records can be written in them. You can invoke the functions of the 
Convert/Reclaim utility from within a program by calling the CONV$RECLAIM 
routine. 

These routines cannot be called from AST level. 

4.2 Using the CONVERT Routines: Examples 

Example 4-1 shows how to use the CONVERT routines in a FORTRAN program. 

Example 4-1 Using the CONVERT Routines in a FORTRAN Program 

* This program calls the routines that perform the 

* functions of the Convert Utility. It creates an 

* indexed output file named CUSTDATA.DAT from the 

* specifications in an FDL file named INDEXED.FDL. 

* The program then loads CUSTDATA.DAT with records 

* from the sequential file SEQ.DAT. No exception 

* file is created. This program also returns all 

* the CONVERT statistics. 

* Program declarations 

IMPLICIT INTEGER*4 (A - Z) 


(continued on next page) 
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Example 4-1 (Cont.) Using the CONVERT Routines in a FORTRAN Program 

* Set up parameter list: number of options, CREATE, 

* NOSHARE, FAST_LOAD, MERGE, APPEND, SORT, WORK_FILES, 

* KEy=0, NOPAD, PAD CHARACTER, NOTRUNCATE, 

* NOEXIT, NOFIXED_CONTROL, FILL_BUCKETS, NOREAD_CHECK, 

* NOWRITE_CHECK, FDL, and NOEXCEPTION. 

* 

INTEGER*4 OPTIONS(19) 

1 /18,1,0,1,0,0,1,2,0,0,0,0,0,0,0,0,0,1,0/ 

* Set up statistics list. Pass an array with the 

* number of statistics that you want. There are four 

* — number of files, number of records, exception 

* records, and good records, in that order. 

INTEGER*4 STATSBLK(5) 74,0,0,0,0/ 

* Declare the file names. 

CHARACTER IN__FILE*7 /'SEQ.DAT'/, 

1 0UT_FILE*12 /'CUSTDATA.DAT'/, 

1 FDL_FILE*11 /'INDEXED.FDL'/ 

* Call the routines in their required order. 

STATUS = CONV$PASS__FILES (IN__FILE, OUT___FILE, FDL__FILE) 

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS)) 

STATUS = CONV$PASS_OPTIONS (OPTIONS) 

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS)) 

STATUS = CONV$CONVERT (STATSBLK) 

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS)) 

* Display the statistics information. 

WRITE (6,1000) (STATSBLK(I),1=2,5) 

1000 FORMAT (IX,'Number of files processed: ',15/, 

1 IX,'Number of records: ',15/, 

1 IX,'Number of exception records: ',15/, 

1 IX,'Number of valid records: ',15) 

END 

Example 4-2 shows how to use the CONVERT routines in a C program. 
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Example 4-2 Using the CONVERT Routines in a C Program 

/* 

** This module calls the routines that perform the functions 
** of the Convert Utility. It creates an indexed output file 
** named CUSTDATA.DAT from the specifications in an FDL file 
** named INDEXED.FDL, and loads CUSTDATA.DAT with records from 
** the sequential file SEQ.DAT. No exception file is created. 

** This module also returns all the CONVERT statistics. 

*/ 

#include <stdio> 

#include <descrip> 

CONVSTAT 0 

{ 

$DESCRIPTOR (input_file, "SEQ.DAT"); 

$DESCRIPTOR (output_file, "CUSTDATA.DAT"); 

$DESCRIPTOR (fdl_file, "INDEXED.FDL"); 

int stat; 

int param_list[19] = { (sizeof param_list / sizeof (int)) - 1 /* arg count */, 
1 /* create */, 

0 /* noshare */, 

1 /* fast_load */, 

0 /* merge */, 

0 /* append */, 

1 /* sort */, 

2 /* work_fiies */, 

0 /* key=0 */, 

0 /* nopad */, 

0 /* pad character */, 

0 /* notruncate */, 

0 /* noexit */, 

0 /* nofixed_control */, 

0 /* fill_buckets */, 

0 /* noread_check */, 

0 /* nowrite_check */, 

1 /* fdl */, 

0 /* noexception */ }; 

/* 

** Have to pass a longword to the CONV$CONVERT ROUTINE with the 
** number of statistics that we want. There are 4 — number of 
** files, number of records, exception records, good records, 

** in that order. This value is passed as first element in the array. 

*/ 

struct { int statistics_count, 
converted_files, 
records_processed, 
exception_records, 

valid_records;} stats =4; /* Init number of statistics */ 

LIB$INIT_TIMER(); /* Start a timer as well */ 

/* 

** First call to pass all the file names 
*/ 

stat = CONV$PASS_FILES ( &input_file, &output_file, &fdl_file); 
if (l(stat & 1)) return stat; 


(continued on next page) 
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Example 4-2 (Cent.) Using the CONVERT Routines in a C Program 

/* 

** Second call to pass particular options chosen as indicated in array. 

*/ 

stat = CONV$PASS_OPTIONS ( param_list ); 
if (!(stat & 1)) return stat; 

/* 

** Final call to perform actual convert, passing statistics block. 

*/ 

stat = CONV$CONVERT ( &stats ); 
if (stat & 1) 

{ 

/* 

** Successful Convert! Print out counterd from statistics 
*/ 

printf ("Number of files processed : %d\n", stats.converted_files); 

printf ("Number of records : %d\n", stats.records_processed); 

printf ("Number of exception records : %d\n", stats.exception_records); 

printf ("Number of valid records : %d\n", stats.valid__records); 

LIB$SHOW__TIMER() ; 

} 

return stat; /* success or failure */ 

} 

Example 4-3 shows how to use the CONV$RECLAIM routine in a FORTRAN 
program. 

Example 4-3 Using the CONV$RECLAIM Routine in a FORTRAN Program 

* This program calls the routine that performs the 

* function of the Convert/Reclaim Utility. It 

* reclaims empty buckets from an indexed file named 

* PR0L3.DAT. It also returns all the CONVERT/RECLAIM 

* statistics. 

* Program declarations 

IMPLICIT INTEGER*4 (A - Z) 

* Set up a statistics block. There are four — data 

* buckets scanned, data buckets reclaimed, index 

* buckets reclaimed, total buckets reclaimed. 

INTEGER*4 0UTSTATS(5) /4,0,0,0,0/ 

* Declare the input file. 

CHARACTER IN_FILE*9 /'PROL3.DAT'/ 

* Call the routine. 

STATUS = CONV$RECLAIM (IN^FILE, OUTSTATS) 

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS)) 


(continued on next page) 
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Example 4-3 (Cent.) Using the CONV$RECLAIM Routine in a FORTRAN 
Program 

* Display the statistics. 

WRITE (6,1000) (OUTSTATS(I),I=2,5) 

1000 FORMAT (IX,'Number of data buckets scanned: ',15/, 

1 lx, 'Number of data buckets reclaimed: ',15/, 

1 IX,'Number of index buckets reclaimed: ',15/, 

1 IX,'Total buckets reclaimed: ',15) 

END 

Example 4—4 shows how to use the CONV$RECLAIM routine in a C program. 

Example 4~4 Using the CONV$RECLAIM Routine in a C Program 

/* 

** This module calls the routine that performs the 
** function of the CONVERT/RECLAIM Utility. It reclaims 
** empty buckets from an indexed file named PROL3.DAT. 

** 

** This module also returns and print all of the 
** CONVERT/RECLAIM statistics. 

*/ 

#include <stdio> 

#include <descrip> 

CONVREC 0 

{ 

$DESCRIPTOR (filename, "PROL3.DAT");/* Provide your file name */ 
struct { int statistics_count, /* must precede actual statistics */ 
scanned^buckets, 
data_buckets__reclaimed, 
index_buckets_reclaimed, 

total__buckets_reclaimed; } stats = 4 /* 4 statistic arguments */; 
int stat; 

/* 

** Perform actual operation. 

*/ 

stat = CONV$RECLAIM ( Sfilename, Sstats ); 
if (stat & 1) 

{ 

/* 

** Successful RECLAIM. Now format and print the counts. 

*/ 

printf ("Data buckets scanned : %d\n", stats.scanned^buckets); 

printf ("Data buckets reclaimed : %d\n", stats.data_buckets__reclaimed); 

printf ("Index buckets reclaimed : %d\n", stats.index__buckets_reclaimed); 

printf ("Total buckets reclaimed : %d\n", stats.total_buckets_reclaimed); 

} 

return stat /* succes or failure */; 

} 


4.3 CONVERT Routines 

The following pages describe the individual CONVERT routines. 
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CONV$CONVERT—Initiate Conversion 

The CONV$CONVERT routine uses the Convert utility to perform the actual 
conversion begun with CONV$PASS_FILES and CONV$PASS_OPTIONS. 
Optionally, the routine can return statistics about the conversion. 

Note too that the CONV$CONVERT routine may return appropriate FDL error 
messages to the calling program, where applicable. 

Format 

CONV$CONVERT [status_block_address] [,flags] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

status_block_address 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

The conversion statistics. The status_block__address argument is the address of 
a variable-length array of longwords that receives statistics about the conversion. 
The format of the array is as follows: 

number of statistics 
number of files 
number of records 
number of exception records 
number of valid records 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags (or masks) that control how the fdl_filespec argument is interpreted 
and how errors are signalled. The flags argument is the address of a longword 
containing control flags (or a mask). If you omit the flags argument or specify 
it as zero, no flags are set. The flags and their meanings are described in the 
following table. 
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Flag 

Function 

CONV$V_FDL_STRING 

Interprets the fdl_filespec argument supplied 
in the call to CONV$PASS_FILES as an FDL 
specification in string form. By default, this 
argument is interpreted as a file name of an FDL 
file. 

CONV$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signalled. 


Condition Values Returned 


SS$_NORMAL 

CONV$_BADBLK 

CONV$_BADLOGIC 

CONV$_BADSORT 

CONV$_CLOSEIN 

CONV$_CLOSEOUT 

CONV$_CONFQUAL 

CONV$_CREA_ERR 

CONV$_CREATEDSTM 

CONV$_DELPRI 

CONV$_DUP 

CONV$_EXTN_ERR 

CONV$_FATALEXC 

CONV$_FILLIM 

CONV$_IDX_LIM 

CONV$_ILL_KEY 

CONV$_ILL_VALUE 

CONV$_INP_FILES 

CONV$_INSVIRMEM 

CONV$_KEY 

CONV$_LOADIDX 

CONV$_NARG 

CONV$_NOKEY 

CONV$_NOTIDX 

CONV$_NOTSEQ 

CONV$_NOWILD 

CONV$_OPENEXC 

CONV$_OPENIN 

CONV$_OPENOUT 


Normal successful completion. 

Invalid option block. 

Internal logic error detected. 

Error trying to sort input file. 

Error closing file specification as input. 

Error closing file specification as output. 
Conflicting qualifiers. 

Error creating output file. 

File specification has been created in stream 
format. 

Cannot delete primary key. 

Duplicate key encountered. 

Unable to extend output file. 

Fatal exception encountered. 

Exceeded open file limit. 

Exceeded maximum index level. 

Illegal key or value out of range. 

Illegal parameter value. 

Too many input files. 

Insufficient virtual memory. 

Invalid record key. 

Error loading secondary index n. 

Wrong number of arguments. 

No such key. 

File is not an indexed file. 

Output file is not a sequential file. 

No wildcard permitted. 

Error opening exception file specification. 
Error opening file specification as input. 
Error opening file specification as output. 
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CONV$_ORDER 

CONV$_PAD 

CONV$_PLV 

CONV$_PROERR 

CONV$_PROL_WRT 

CONV$_READERR 

CONV$_REX 

CONV$_RMS 

CONV$_RSK 

CONV$_RSZ 

CONV$_RTL 

CONV$_RTS 

CONV$_SEQ 

CONV$_UDF_BKS 

conv$_udf_blk 

CONV$_VALERR 

CONV$_VFC 

CONV$_WRITEERR 


Routine called out of order. 

PAD option ignored; output record format not 
fixed. 

Unsupported prolog version. 

Error reading prolog. 

Prolog write error. 

Error reading file specification. 

Record already exists. 

Record caused RMS severe error. 

Record shorter than primary key. 

Record does not fit in block/bucket. 

Record longer than maximum record length. 
Record too short for fixed record format file. 
Record not in order. 

Cannot convert UDF records into spanned file. 
Cannot fit UDF records into single block bucket. 
Specified value is out of legal range. 

Record too short to fill fixed part of VFC record. 
Error writing file specification. 
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CONV$PASS_FILES—Specify Conversion Files 

The CONV$PASS_FILES routine specifies a file to be converted using the 
CONV$CONVERT routine. 


Format 


CONV$PASS_FILES inpuMilespec ,output_filespec [,fdLfilespec] 
[,exception_filespec] [,flags] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

inpuMilespec 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 

The name of the file to be converted. The input_filespec argument is the 
address of a string descriptor pointing to the name of the file to be converted. 

outpuMilespec 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 

The name of the file that receives the records from the input file. The output^ 
filespec argument is the address of a string descriptor pointing to the name of 
the file that receives the records from the input file. 

fdLfilespec 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 

The name of the FDL file that defines the output file. The fdl_filespec argument 
is the address of a string descriptor pointing to the name of the FDL file. 

exception_filespec 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 
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The name of the file that receives copies of records that cannot be written to 
the output file. The exception_filespec argument is the address of a string 
descriptor pointing to this name. 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags (or masks) that control how the fdLfilespec argument is interpreted 
and how errors are signalled. The flags argument is the address of a longword 
containing the control fiags (or mask). If you omit this argument or specify it as 
zero, no fiags are set. If you specify a fiag, it remains in effect until you explicitly 
reset it in a subsequent call to a CONVERT routine. 

The fiags and their meanings are described in the following table. 


Flag 

Function 

CONV$V_FDL_STRING 

Interprets the fdl_filespec argument as an FDL 
specification in string form. By default, this 
argument is interpreted as a file name of an FDL 
file. 

CONV$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signalled. 


Description 

The CONV$PASS_FILES routine specifies a file to be converted using the 
CONV$CONVERT routine. A single call to CONV$PASS_FILES allows you to 
specify an input file, an output file, an FDL file, and an exception file. If you 
have multiple input files, you must call CONV$PASS_FILES once for each file. 
You need to specify only the input_filespec argument for the additional files, as 
follows: 

status = CONV$PASS_FILES (input_filespec) 

The additional calls must immediately follow the original call that specified the 
output file specification. You may specify as many as 9 additional files for a 
maximum total of 10. 

Wildcard characters are not allowed in the file specifications passed to the 
CONVERT routines. 
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Condition Vaiues Returned 

SS$_NORMAL 

CONV$_INP_FILES 

CONV$_INSVIRMEM 

CONV$_NARG 

CONV$_ORDER 


Normal successful completion. 
Too many input files. 
Insufficient virtual memory. 
Wrong number of arguments. 
Routine called out of order. 
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CONV$PASS_OPTIONS—Specify Processing Options 

The CONV$PASS_OPTIONS routine specifies which qualifiers are to be used by 
the Convert utility (CONVERT). 


Format 

CONV$PASS_OPTIONS [parameter_list_address] [,flags] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

parameter_list_address 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Parameter list specifying information about the CONVERT qualifiers. The 
parameter_list_address argument is the address of a variable-length array 
of longwords. The first longword in the array is the number of parameters in 
the array. Each subsequent longword in the array (from the second one on) is 
associated with one of the CONVERT qualifiers. These functions are described in 
the OpenVMS Record Management Utilities Reference Manual. 

To set one of the CONVERT qualifiers, you place a i in the longword associated 
with that qualifier. If you do not want to set one of the qualifiers (which has 
the same effect as using the negative form of the qualifier on the CONVERT 
command), you place a (9 in the correct longword. 

If you do not specify parameter Jist_address, then the following default values 
apply. You can also take all default values by passing the address of a longword 
that contains 0, which means a parameter list of 0 longwords. 

If you have specified all the values you want set, you may want to take the default 
values for all subsequent qualifiers in the list. You may omit the subsequent ones 
if you give the array length in the first longword. This is why the first longword 
contains a count of the qualifiers. 
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The qualifiers must appear in the following order: 


Qualifier 

Default Value (in 
Longwords) 

Default CONVERT Value 

CREATE 

1 

/CREATE 

SHARE 

0 

/NOSHARE 

FAST_LOAD 

1 

/FAST.LOAD 

MERGE 

0 

/NOMERGE 

APPEND 

0 

/NOAPPEND 

SORT 

1 

/SORT 

WORK_FILES 

2 

/WORK_FILES=2 

KEY 

0 

/KEY=0 

PAD 

0 

/NOPAD 

Pad character 

0 

Pad character=0 

TRUNCATE 

0 

/NOTRUNCATE 

EXIT 

0 

/NOEXIT 

FIXED.CONTROL 

0 

/NOFIXED_CONTROL 

FILL.BUCKETS 

0 

/NOFILL_BUCKETS 

READ_CHECK 

0 

/NOREAD.CHECK 

WRITE.CHECK 

0 

/NOWRITE_CHECK 

FDL 

0 

/NOFDL 

EXCEPTION 

0 

/NOEXCEPTION 

PROLOG 

No default 

System or process default 


If you want to use the default null character for the PAD qualifier, you should 
specify 0 in the pad character longword. You can also specify the default null 
character by omitting the pad character longword. However, in this case, you 
must also take the default values for all subsequent qualifiers. To specify a pad 
character other than 0, place the ASCII value of the character you want to use in 
the PAD qualifier longword. 

If you specify /EXIT and the utility encounters an exception record, then 
CONVERT returns with a fatal exception status. 

If you specify an FDL file specification in the CONV$PASS_FILES routine, 
you must place a 1 in the FDL longword. If you also specify an exceptions file 
specification in the CONV$PASS_FILES routine, you must place a 7 in the 
EXCEPTION longword. You may specify either, both, or neither of these files, 
but the values in the CONV$PASS_FILES call must match the values in the 
parameter list. If they do not, the routine returns an error. 

If you specify the PROLOG longword, note that this overrides the KEY PROLOG 
attribute supplied by the FDL file. You must supply one of three values for the 
PROLOG longword if you use it. The three values are 0, 2, and 3. The value 
0 means that you want to use the system or process prolog type. The value 2 
means that you want to create a Prolog 1 or 2 file in all instances, even when 
circumstances would allow you to create a Prolog 3 file. The value 3 means that 
you want to create a Prolog 3 file and, if circumstances do not allow you to, you 
want the conversion to fail. 
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flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags (or masks) that control how the fdl_filespec argument is interpreted 
and how errors are signalled. The flags argument is the address of a longword 


containing the control flags (or a mask). If you omit this argument or specify it as 
zero, no flags are set. If you specify a flag, it remains in effect until you explicitly 
reset it in a subsequent call to a CONVERT routine. 

The flags and their meanings are described in the following table. 

Flag 

Function 

CONV$V_FDL_STRING 

Interprets the fdl_filespec argument supplied 
in the call to CONV$PASS_FILES as an FDL 
specification in string form. By default, this 
argument is interpreted as a file name of an FDL 
file. 

FDL$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 

This argument is optional, 
signalled. 

By default, an error status is returned rather than 


Description 


You can use an options array to generate programmatic CONVERT commands. 
For example, you can generate the following programmatic CONVERT command 
by configuring the options array described by the pseudo code that follows the 
example command line. 


$ C0NVERT/FAST_L0AD/S0RT/W0RK_FILES=6/EXIT 


OPTIONS ARRAY [12] 
OPTIONS[0] = 12 
0PTI0NS[1] = 1 
OPTIONS[2] = 0 
0PTI0NS[3] = 1 
0PTI0NS[4] = 0 
0PTI0NS[5] = 0 
0PTI0NS[6] = 1 
0PTI0NS[7] = 6 
0PTI0NS[8] = 0 
0PTI0NS[9] = 0 
OPTIONS[10] = 0 
OPTIONS[11] = 0 
OPTIONS[12] = 1 


{Allocate a 13-cell array} 

{Number of options] 

{Specifies the /CREATE option} 
{Specifies the /NOSHARE option} 
{Specifies the /FASTLOAD option} 
{Specifies the /NOMERGE option} 
{Specifies the /NOAPPEND option} 
{Specifies the /SORT option} 
{Specifies the /WORKFILES=6 option} 
{Specifies the /KEy=0 option} 
{Specifies the /NOPAD option} 
{Specifies the null pad character} 
{Specifies the /NOTRUNCATE option} 
{Specifies the /EXIT option} 
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Condition Values Returned 

SS$_NORMAL 

CONV$_BADBLK 

CONV$_CONFQUAL 

CONV$_INSVIRMEM 

CONV$_NARG 

CONV$_OPENEXC 

CONV$_ORDER 


Normal successful completion. 
Invalid option block. 

Conflicting qualifiers. 

Insufficient virtual memory. 

Wrong number of arguments. 

Error opening exception file filespec. 
Routine called out of order. 
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CONV$RECLAIM—Invoke Convert/Reclaim Utility 

The CONV$RECLAIM routine invokes the functions of the Convert/Reclaim 
utility. 


Format 


CONV$RECLAIM inpuMilespec [,statistics_blk] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

input._filespec 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 

Name of the Prolog 3 indexed file to be reclaimed. The input_filespec argument 
is the address of a string descriptor pointing to the name of the Prolog 3 indexed 
file. 


statistics.bik 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_unsigned 
longword (unsigned) 
modify 
by reference 


Bucket reclamation statistics. The statistics_blk argument is the address of a 
variable-length array of longwords to receive statistics on the bucket reclamation. 
You can choose which statistics you want returned by specifying a number in the 
first element of the array. This number determines how many of the four possible 
statistics the routine returns. Depending on the number chosen, the routine 
returns the statistics in the statistics array in the order specified by the following 
format: 


A: Number of statistics 

Data buckets scanned 
Data buckets reclaimed 
Index buckets reclaimed 
Total buckets reclaimed 
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Condition Vaiues Returned 

SS$_NORMAL 

CONV$_BADLOGIC 

CONV$_INSVIRMEM 

CONV$_INVBKT 

CONV$_NOTIDX 

CONV$_OPENIN 

CONV$_PLV 

CONV$_PROERR 

CONV$_PROL_WRT 

CONV$_READERR 

CONV$_NOWILD 

CONV$_WRITEERR 


Normal successful completion. 
Internal logic error detected. 
Insufficient virtual memory. 
Invalid bucket at VBN n. 

File is not an index file. 

Error opening filespec as input. 
Unsupported prolog version. 
Error reading prolog. 

Prolog write error. 

Error reading filespec. 

No wildcard permitted. 

Error writing output file. 
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The set of routines described in this chapter comprises the Data Compression 
/Expansion (DCX) facility. There is no DCL-level interface to this facility, nor is 
there a DCX utility 

5.1 Introduction to DCX Routines 

Using the DCX routines described in this chapter, you can decrease the size of 
text, binary data, images, and any other type of data. Compressed data uses less 
space, but there is a trade-off in terms of access time to the data. Compressed 
data must first be expanded to its original state before it is usable. Thus, 
infrequently accessed data makes a good candidate for data compression. 

The DCX facility provides routines that analyze and compress data records 
and expand the compressed records to their original state. In this process, no 
information is lost. A data record that has been compressed and then expanded 
is in the same state as it was before it was compressed. 

Most collections of data can be reduced in size by DCX. However, there is no 
guarantee that the size of an individual data record will always be smaller after 
compression; in fact, some may grow larger. 

The DCX facility allows for the independent analysis, compression, and expansion 
of more than one stream of data records at the same time. This capability is 
provided by means of a “context variable,” which is an argument in each DCX 
routine. Most applications have no need for this capability; for these applications, 
there is a single context variable. 

Some of the DCX routines make calls to various Run-Time Library (RTL) 
routines, for example, LIB$GET_VM. If any of these RTL routines fails, a return 
status code indicating the cause of the failure is returned. In such a case, you 
must refer to the documentation of the appropriate RTL routine to determine the 
cause of the failure. The status codes documented in this chapter are primarily 
DCX status codes. 

Note also that the application program should declare referenced constants and 
return status symbols as external symbols; these symbols are resolved upon 
linking with the utility shareable image. 

5.1.1 Compression Routines 

Compressing a file with the DCX routines involves the following steps. (See 
Example 5—1.) 

1. Initialize an analysis work area—Use the DCX$ANALYZE_INIT routine to 
initialize a work area for analyzing the records. The first (and, typically, the 
only) argument passed to DCX$ANALYZE_INIT is an integer variable for 
storing the context value. The data compression facility assigns a value to the 
context variable and associates the value with the created work area. Each 
time you want to analyze a record in that area, specify the associated context 
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variable. You can analyze two or more files at once by creating a different 
work area for each file, giving each area a different context variable, and 
analyzing the records of each file in the appropriate work area. 

2. Analyze the records in the file—Use the DCX$ANALYZE_DATA routine to 
pass each record in the file to an analysis work area. During analysis, the 
data compression facility gathers information that DCX$MAKE_MAP uses 
to create the compression/expansion function for the file. To ensure that the 
first b3d;e of each record is passed to the data compression facility rather 
than being interpreted as a carriage control, specify CARRIAGE CONTROL = 
NONE when you open the file to be compressed. 

3. Create the compression/expansion function—Use the DCX$MAKE_MAP 
routine to create the compression/expansion function. You pass DCX$MAKE_ 
MAP a context variable, and DCX$MAKE_MAP uses the information stored 
in the associated work area to compute a compression/expansion function for 
the records being compressed. If DCX$MAKE_MAP returns a status value of 
DCX$_AGAIN, repeat steps 2 and 3 until DCX$MAKE_MAP returns a status 
of DCX$_NORMAL, indicating that a compression/expansion function has 
been created. 

In Example 5-1, the integer function GET_MAP analyzes each record in 
the file to be compressed and invokes DCX$MAKE_MAP to create the 
compression/expansion function. The function value of GET_MAP is the 
return status of DCX$MAKE_MAP, and the address and length of the 
compression/expansion function are returned in GET_MAP’s argument list. 
The main program, COMPRESS_FILES, invokes the GET_MAP function, 
examines its function value, and, if necessary, invokes GET_MAP again (see 
the ANALYZE DATA program section). 

4. Clean up the analysis work area—Use the DCX$ANALYZE_DONE routine 
to delete a work area. Identify the work area to be deleted by passing 
DCX$ANALYZE_DONE a context variable. 

5. Save the compression/expansion function—^You cannot expand compressed 
records without the compression/expansion function. Therefore, before 
compressing the records, write the compression/expansion function to the file 
that will contain the compressed records. 

If your programming language cannot use an address directly, pass the 
address of the compression/expansion function to a subprogram (WRITE_ 
MAP in Example 5-1). Pass the subprogram the length of the compression 
/expansion function as well. 

In the subprogram, declare the dummy argument corresponding to the 
function address as a one-dimensional, adjustable, byte array. Declare the 
dummy argument corresponding to the function length as an integer, and use 
it to dimension the adjustable array. Write the function length and the array 
containing the function to the file that is to contain the compressed records. 
(The length must be stored so that you can read the function from the file 
using unformatted I/O; see Section 5.1.2.) 

6. Compress each record—Use the DCX$COMPRESS_INIT routine to initialize 
a compression work area. Specify a context variable for the compression area 
just as for the analysis area. 
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Use the DCX$COMPRESS_DATA routine to compress each record. As you 
compress each record, use unformatted I/O to write the compressed record 
to the file containing the compression/expansion function. For each record, 
write the length of the record and the substring containing the record. See 
the COMPRESS DATA section in Example 5-1. (The length is stored with 
the substring so that you can read the compressed record from the file using 
unformatted I/O; see Section 5.1.2.) 

7. Use DCX$COMPRESS_DONE to delete the work area created by 

DCX$COMPRESS_INIT. Identify the work area to be deleted by passing 
DCX$COMPRESS_DATA a context variable. Use LIB$FREE_VM to free the 
virtual memory that DCX$MAKE_MAP used for the compression/expansion 
function. 

Example 5—1 shows how to use the callable DCX routines to compress a file in a 

DEC Fortran program. 


Example 5-1 Compressing a File in a DEC Fortran Program 

PROGRAM COMPRESS_FILES 
! COMPRESSION OF FILES 

! status variable 
INTEGER STATUS, 

2 lOSTAT, 

2 IO_OK, 

2 STATUS_OK 

PARAMETER (IO_OK = 0) 

PARAMETER (STATUS__0K = 1) 

INCLUDE '($F0RDEF)' 

EXTERNAL DCX$__AGAIN 

1 context variable 
INTEGER CONTEXT 

! compression/expansion function 
INTEGER MAP, 

2 MAP_LEN 

! normal file name, length, and logical unit number 
CHARACTER*256 N0RM__NAME 
INTEGER*2 NORM_LEN 
INTEGER NORM_LUN 

! compressed file name, length, and logical unit number 
CHARACTER*256 C0MP_NAME 
INTEGER*2 C0MP__LEN 
INTEGER COMP LUN 


! Logical end-of-file 
LOGICAL EOF 

! record buffers; 32764 is maximum record size 
CHARACTER*32764 RECORD, 

2 RECORD2 

INTEGER RECORD_LEN, 

2 REC0RD2_LEN 

1 user routine 
INTEGER GET__MAP, 

2 WRITE MAP 


(continued on next page) 


DCX-3 





Data Compression/Expansion (DCX) Routines 
5.1 Introduction to DCX Routines 


Example 5-1 (Cent.) Compressing a File in a DEC Fortran Program 

! Library procedures 
INTEGER DCX$MALYZE_INIT, 

2 DCX$ANALYZE_DONE, 

2 DCX$COMPRESS_INIT, 

2 DCX$COMPRESS_DATA, 

2 DCX$COMPRESS_DONE, 

2 LIB$GET_INPUT, 

2 LIB$GET_LUN, 

2 LIB$FREE_VM 

! get name of file to be compressed and open it 
STATUS = LIB$GET_INPUT (NORM_NAME, 

2 'File to compress: 

2 NORM_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL {%VAL(STATUS)) 

STATUS = LIB$GET_LUN (NORM_LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

OPEN (UNIT = NORM_LUN, 

2 FILE = N0RM_NAME(1:N0RM_LEN), 

2 CARRIAGECONTROL = 'NONE', 

2 STATUS = 'OLD') 


I ************ 

! ANALYZE DATA 

1 ************ 

! initialize work area 

STATUS = DCX$ANALYZE_INIT (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
! get compression/expansion function (map) 

STATUS = GET_MAP (NORM_LUN, 

2 CONTEXT, 

2 MAP, 

2 MAP_LEN) 

DO WHILE (STATUS .EQ. %LOC(DCX$_AGAIN)) 

! go back to beginning of file 
REWIND (UNIT = NORM_LUN) 

! try map again 

STATUS = GET_MAP (NORM^LUN, 

2 CONTEXT, 

2 MAP, 

2 MAP_LEN) 

END DO 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

! clean up work area 

STATUS = DCX$ANALYZE_DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 


(continued on next page) 
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Example 5-1 (Cent.) Compressing a File in a DEC Fortran Program 

I ************* 

! COMPRESS DATA 

1 ************* 

! go back to beginning of file to be compressed 
REWIND (UNIT = NORM_LUN) 

! open file to hold compressed records 
STATUS = LIB$GET_LUN (COMP__LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

STATUS = LIB$GET_INPUT (COMP_NAME, 

2 'File for compressed records: ', 

2 COMP_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

OPEN (UNIT = COMP^LUN, 

2 FILE = C0MP_NAME(1:C0MP_LEN), 

2 STATUS = 'NEW', 

2 FORM = 'UNFORMATTED') 

! initialize work area 

STATUS = DCX$COMPRESS_INIT (CONTEXT, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

! write compression/expansion function to new file 
CALL WRITE_MAP (COMP_LUN, 

2 %VAL(MAP), 

2 MAP__LEN) 

! read record from file to be compressed 
EOF = .FALSE. 

READ (UNIT = NORM__LUN, 

2 FMT = '(Q,A)', 

2 lOSTAT = lOSTAT) RECORD_LEN, 

2 RECORD(1:RECORD_LEN) 

IF (lOSTAT .NE. IO_OK) THEN 
CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS)) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS_OK 
END IF 
END IF 


(continued on next page) 
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Example 5-1 (Cent.) Compressing a File in a DEC Fortran Program 


DO WHILE (.NOT. EOF) 

1 compress the record 

STATUS = DCX$COMPRESS_DATA (CONTEXT, 

2 RECORD(1:RECORD_LEN), 

2 REC0RD2, 

2 REC0RD2_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

! write compressed record to new file 

WRITE (UNIT = COMP__LUN) REC0RD2__LEN 

WRITE (UNIT = COMP_LUN) REC0RD2 (1 :REC0RD2__LEN) 

! read from file to be compressed 
READ (UNIT = NORM_LUN, 

2 FMT = '(Q,A)', 

2 lOSTAT = lOSTAT) RECORD__LEN, 

2 RECORD (1:RECORD^LEN) 

IF (lOSTAT .NE. IO_OK) THEN 
CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS)) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS_OK 
END IF 
END IF 
END DO 

! close files and clean up work area 
CLOSE (NORM^LUN) 

CLOSE (COMP__LUN) 

STATUS = LIB$FREE_VM (MAP_LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 
STATUS = DCX$COMPRESS__DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

END 


INTEGER FUNCTION GET_MAP (LUN, 

2 CONTEXT, 

2 MAP, 

2 MAP^LEN) 

I 


! passed 
! passed 
! returned 
! returned 


Analyzes records in file opened on logical 
unit LUN and then attempts to create a 
compression/expansion function using 
DCX$MAKE MAP. 


! dummy arguments 
! context variable 
INTEGER CONTEXT 
! logical unit number 
INTEGER LUN 

! compression/expansion function 
INTEGER MAP, 

2 MAP LEN 


(continued on next page) 
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Example 5-1 (Cent.) Compressing a File in a DEC Fortran Program 

! status variable 
INTEGER STATUS, 

2 lOSTAT, 

2 IO___OK, 

2 STATUS_OK 

PARAMETER (IO_OK = 0) 

PARAMETER (STATUS_0K = 1) 

INCLUDE '($F0RDEF)' 

! Logical end-of-file 
LOGICAL EOF 

! record buffer; 32764 is the maximum record size 
CHARACTER*32764 RECORD 
INTEGER RECORD__LEN 

! library procedures 
INTEGER DCX$ANALYZE_DATA, 

2 DCX$MAKE_MAP 

! analyze records 
EOF = .FALSE. 

READ (UNIT = LUN, 

2 FMT = '(Q,A) 

2 lOSTAT = lOSTAT) RECORD__LEN,RECORD 

IF (lOSTAT .NE. IO__OK) THEN 
CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$__ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS)) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS_OK 
END IF 
END IF 

DO WHILE (.NOT. EOF) 

STATUS = DCX$ANALYZE_DATA (CONTEXT, 

2 RECORD(1:RECORD_LEN)) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

READ (UNIT = LUN, 

2 FMT = ' (Q,A) ' , 

2 lOSTAT = lOSTAT) RECORD__LEN,RECORD 

IF (lOSTAT .NE. IO_OK) THEN 
CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS)) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS_OK 
END IF 
END IF 
END DO 

STATUS = DCX$MAKE_MAP (CONTEXT, 

2 MAP, 

2 MAP_LEN) 

GET_MAP = STATUS 

END 


(continued on next page) 
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Example 5-1 (Cont.) Compressing a File in a DEC Fortran Program 

SUBROUTINE WRITE_MAP (LUN, ! passed 
2 MAP, ! passed 

2 MAP_LEN) ! passed 

IMPLICIT INTEGER!A-Z) 

! write compression/expansion function 
I to file of compressed data 

1 dummy arguments 

INTEGER LUN, ! logical unit of file 

2 MAP_LEN ! length of function 

BYTE MAP (MAP_LEN) ! compression/expansion function 

! write map length 
WRITE (UNIT = LUN) MAP_LEN 
I write map 

WRITE (UNIT = LUN) MAP 
END 

5.1.2 Expansion Routines 

Expanding a file with the DCX routines involves the following steps: 

1. Read the compression/expansion function—When reading the compression 
/expansion function from the compressed file, do not make any assumptions 
about the function’s size. The best practice is to read the length of the 
function from the compressed file and then invoke the LIB$GET_VM routine 
to get the necessary amount of storage for the function. LIB$GET_VM 
returns the address of the first byte of the storage area. 

If your programming language cannot use an address directly, pass the 
address of the storage area to a subprogram (READ_MAP in Example 5-2). 
Pass the subprogram the length of the compression/expansion function as 
well. 

In the subprogram, declare the dummy argument corresponding to the 
storage address as a one-dimensional, adjustable, byte array. Declare the 
dummy argument corresponding to the function length as an integer and 
use it to dimension the adjustable array. Read the compression/expansion 
function from the compressed file into the dummy array. Because the 
compression/expansion function is stored in the subprogram, do not return to 
the main program until you have expanded all of the compressed records. 

2. Initialize an expansion work area—Use the DCX$EXPAND_INIT routine to 
initialize a work area for expanding the records. The first argument passed 
to DCX$EXPAND_INIT is an integer variable to contain a context value 
(see step 1 in Section 5.1.1). The second argument is the address of the 
compression/expansion function. 

3. Expand the records—Use the DCX$EXPAND_DATA routine to expand each 
record. 

4. Clean up the work area—Use the DCX$EXPAND_DONE routine to delete 
an expansion work area. Identify the work area to be deleted by passing 
DCX$EXPAND_DONE a context variable. 
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Example 5—2 expands a compressed file. The first record of the compressed file is 
an integer containing the number of bytes in the compression/expansion function. 
The second record is the compression/expansion function. The remainder of the 
file contains the compressed records. Each compressed record is stored as two 
records; an integer containing the length of the record and a substring containing 
the record. 


Example 5-2 Expanding a Compressed File in a DEC Fortran Program 

PROGRAM EXPAND_FILES 
IMPLICIT INTEGER{A-Z) 

! EXPANSION OF COMPRESSED FILES 

! file names, lengths, and logical unit numbers 
CHARACTER*256 OLD_FILE, 

2 NEW_FILE 

INTEGER*2 OLD_LEN, 

2 NEW_LEN 

INTEGER OLD_LUN, 

2 NEW_LUN 

! length of compression/expansion function 
INTEGER MAP, 

2 MAP_LEN 

! user routine 
EXTERNAL EXPAND_DATA 

! library procedures 
INTEGER LIB$GET_LUN, 

2 LIB$GET_INPUT, 

2 LIB$GET_VM, 

2 LIB$FREE_VM 

! open file to expand 
STATUS = LIB$GET_LUN {OLD_LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

STATUS = LIB$GET_INPUT {OLD_FILE, 

2 'File to expand: ', 

2 OLD_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

OPEN (UNIT = OLD_LUN, 

2 STATUS = 'OLD', 

2 FILE = 0LD_FILE(1:0LD_LEN), 

2 FORM = 'UNFORMATTED') 

! open file to hold expanded data 
STATUS = LIB$GET_LUN (NEW_LUN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

STATUS = LIB$GET_INPUT (NEW_FILE, 

2 'File to hold expanded data: ', 

2 NEW_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

OPEN (UNIT = NEW_LUN, 

2 STATUS = 'NEW', 

2 CARRIAGECONTROL = 'LIST', 

2 FILE = NEW_FILE(1:NEW_LEN)) 


(continued on next page) 
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Example 5-2 (Cent.) Expanding a Compressed File in a DEC Fortran Program 

! expand file 

! get length of compression/expansion function 
READ (UNIT = OLD__LUN) MAP__LEN 
STATUS = LIB$GET_VM (MAP_LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

! expand records 

CALL EXPAND_DATA (%VAL(MAP), 

2 MAP_LEN, ! length of function 

2 OLD__LUN, ! compressed data file 

2 NEW__LUN) ! expanded data file 

1 delete virtual memory used for function 
STATUS = LIB$FREE_VM (MAP_LEN, 

2 MAP) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

END 

SUBROUTINE EXPAND_DATA 
2 
2 
2 

1 expand data program 
! dummy arguments 

INTEGER MAP__LEN, ! length of expansion function 

2 OLD_LUN, ! logical unit of compressed file 

2 NEW__LUN I logical unit of expanded file 

BYTE MAP(MAP_LEN) ! array containing the function 

! status variables 
INTEGER STATUS, 

2 lOSTAT, 

2 IO__OK, 

2 STATUS__OK 

PARAMETER (IO_OK = 0) 

PARAMETER (STATUS_OK = 1) 

INCLUDE '($FORDEF)' 

1 context variable 
INTEGER CONTEXT 

! logical end_of_file 
LOGICAL EOF 
! record buffers 
CHARACTER*32764 RECORD, 

2 RECORD2 
INTEGER RECORD_LEN, 

2 RECORD2__LEN 

1 library procedures 
INTEGER DCX$EXPAND_INIT, 

2 DCX$EXPAND_DATA, 

2 DCX$EXPAND_DONE 


(MAP, ! passed 
MAP__LEN, ! passed 
OLD__LUN, ! passed 
NEW_LUN) 1 passed 


(continued on next page) 


DCX-10 




Data Compression/Expansion (DCX) Routines 
5.1 Introduction to DCX Routines 


Example 5-2 (Cont.) Expanding a Compressed File in a DEC Fortran Program 

1 read data compression/expansion function 
READ (UNIT = OLD_LUN) MAP 

! initialize work area 

STATUS = DCX$EXPAND_INIT (CONTEXT, 

2 %L0C(MAP(1))) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

! expand records 
EOF = .FALSE. 

! read length of compressed record 
READ (UNIT = OLD__LUN, 

2 lOSTAT = lOSTAT) RECORD_LEN 
IF (lOSTAT .NE. IO_OK) THEN 
CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS)) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS_OK 
END IF 
END IF 

DO WHILE (.NOT. EOF) 

! read compressed record 

READ (UNIT = OLD__LUN) RECORD (1:RECORD_LEN) 

! expand record 

STATUS = DCX$EXPAND_DATA (CONTEXT, 

2 RECORD(1:RECORD_LEN), 

2 REC0RD2, 

2 REC0RD2__LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

! write expanded record to new file 
WRITE (UNIT = NEW^LUN, 

2 FMT = '(A)') REC0RD2(1:REC0RD2_LEN) 

! read length of compressed record 
READ (UNIT = OLD^LUN, 

2 lOSTAT = lOSTAT) RECORD_LEN 

IF (lOSTAT .NE. IO_OK) THEN 
CALL ERRSNS (,,,,STATUS) 

IF (STATUS .NE. FOR$_ENDDURREA) THEN 
CALL LIB$SIGNAL (%VAL(STATUS)) 

ELSE 

EOF = .TRUE. 

STATUS = STATUS_OK 
END IF 
END IF 
END DO 

1 clean up work area 

STATUS = DCX$EXPAND_DONE (CONTEXT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 

END 


5.2 DCX Routines 

The following pages describe the individual DCX routines. 
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DCX$ANALYZE_DATA 


DCX$ANALYZE_DATA—Perform Statistical Analysis on a Data 

Record 

The DCX$ANALYZE_DATA routine performs statistical analysis on a data record. 

The results of the analysis are accumulated internally in the context area and are 
used by the DCX$MAKE_MAP routine to compute the mapping function. 


Format 

DCX$ANALYZE_DATA context .record 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access read only 

mechanism by reference 

Value identifying the data stream that DCX$ANALYZE_DATA analyzes. 

The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 

record 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Record to be analyzed. DCX$ANALYZE_DATA reads the record argument, 
which is the address of a descriptor for the record string. The maximum length of 
the record string is 65,535 characters. 


Description 

The DCX$ANALYZE_DATA routine performs statistical analysis on a single data 
record. This routine is called once for each data record to be analyzed. 

During analysis, the data compression facility gathers information that 
DCX$MAKE_MAP uses to create the compression/expansion function for the 
file. After the data records have been analyzed, you call the DCX$MAKE_MAP 
routine. Upon receiving the DCX$_AGAIN status code from DCX$MAKE_ 

MAP, you must again analyze the same data records (in the same order) using 
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DCX$ANALYZE_DATA 

DCX$ANALYZE_DATA and then call DCX$MAKE_MAP again. On the second 
iteration, DCX$MAKE_MAP returns the DCX$_NORMAL status code, and the 
data analysis is complete. 

Condition Values Returned 

DCX$_INVCTX Error. The context variable is invalid, or the 

context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 

DCX$_NORMAL Successful completion. 

This routine also returns any Condition Values Returned by LIB$ANALYZE_ 
SDESC_R2. 
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DCX$ANALYZE_DONE—Specify Analysis Completed 

The DCX$ANALYZE_DONE routine deletes the context area and sets the context 
variable to zero, thus undoing the work of the DCX$ANALYZE_INIT routine. 

You call DCX$ANALYZE_DONE after data records have been analyzed and the 
DCX$MAKE_MAP routine has created the map. 

Format 

DCX$ANALYZE_DONE context 

Returns 

OpenVMS usage cond_value 
type longword 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

context 

OpenVMS usage context 
type longword 

access modify 

mechanism by reference 

Value identifying the data stream that DCX$ANALYZE_DONE deletes. 

The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 

Condition Values Returned 

DCX$_INVCTX Error. The context variable is invalid, or the 

context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 

DCX$_NORMAL Successful completion. 

This routine also returns any condition values returned by LIB$FREE_VM. 
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DCX$ANALYZEJNIT 


DCX$ANALYZEJNIT—Initialize Analysis Context 

The DCX$ANALYZE_INIT routine initializes the context area for a statistical 
analysis of the data records to be compressed. 


Format 

DCX$ANALYZE_INIT context [,item_code ,item_value] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access write only 

mechanism by reference 

Value identifying the data stream that DCX$ANALYZE_INIT initializes. 

The context argument is the address of a longword containing this value. 
DCX$ANALYZE_INIT writes this context into the context argument; you should 
not modify its value. You can define multiple context arguments to identify 
multiple data streams that are processed simultaneously. 

item_code 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Item code specifying information that you want DCX$ANALYZE_INIT to use 
in its analysis of data records and in its computation of the mapping function. 
DCX$ANALYZE_INIT reads this item_code argument, which is the address of 
the longword contained in the item code. 

For each item_code argument specified in the call, you must also specify a 
corresponding item_value argument. The item_value argument contains the 
interpretation of the item_code argument. 

The following symbolic names are the five legal values of the item_code 
argument: 

DCX$C_BOUNDED 

DCX$C_EST_BYTES 

DCX$C_EST_RECORDS 

DCX$C_LIST 

DCX$C_ONE_PASS 
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item_value 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Value of the corresponding item_code argument. DCX$ANALYZE_INIT reads 
the item^value argument, which is the address of a longword containing the 
item value. 

The item_code and item_value arguments always occur as a pair, and together 
they specify one piece of “advice” for the DCX routines to use in computing the 
map function. Note that, unless stated otherwise in the list of item codes and 
item values, no piece of “advice” is binding on DCX; that is, DCX is free to follow 
or not to follow the “advice.” 

The following table shows, for each item_code argument, the possible values for 
the corresponding item_value argument. 


Item Code Corresponding Item Value 

DCX$C_BOUNDED A Boolean variable. If bit <0> is true (equals i), 

you are stating your intention to submit for analysis 
all data records that will be compressed; doing so 
often enables DCX to compute a better compression 
algorithm. If bit <0> is false (equals 0) or if the 
DCX$C_BOUNDED item code is not specified, DCX 
computes a compression algorithm without regard 
for whether all records to be compressed will also be 
submitted for analysis. 

DCX$C_EST_BYTES A longword value containing your estimate of the 

total number of data bytes that will be submitted 
for compression. This estimate is useful in those 
cases where fewer than the total number of bytes 
are presented for analysis. If you do not specify the 
DCX$C_EST__BYTES item code, DCX submits for 
compression the same number of bytes that was 
presented for analysis. Note that you may specify 
DCX$C_EST^RECORDS or DCX$C_EST_BYTES, 
or both. 

DCX$C_EST_RECORDS A longword value containing your estimate of the 

total number of data records that will be submitted 
for compression. This estimate is useful in those 
cases where fewer than the total number of records 
are presented for analysis. If you do not specify the 
DCX$C_EST_RECORDS item code, DCX submits 
for compression the same number of b 3 d;es that was 
presented for analysis. 
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Corresponding Item Value 

Address of an array of 2*72+1 longwords. The 
first longword in the array contains the value 
2*71+1. The remaining longwords are paired; there 
are n pairs. The first member of the pair is an 
item code, and the second member of the pair is 
the address of its corresponding item value. The 
DCX$C_LIST item code allows you to construct an 
array of item-code and item-value pairs and then 
to pass the entire array to DCX$ANALYZE_INIT. 
This is useful when your language has difficulty 
interpreting variable-length argument lists. Note 
that the DCX$C_LIST item code may be specified, 
in a single call, alone or together with any of the 
other item-code and item-value pairs. 

A Boolean variable. If bit <0> is true (equals 1), you 
make a binding request that DCX make only one 
pass over the data to be analyzed. If bit <0> is false 
(equals 0) or if the DCX$C_ONE_PASS item code is 
not specified, DCX may make multiple passes over 
the data, as required. Typically, DCX makes one 
pass. 

Description 

The DCX$ANALYZE_INIT routine initializes the context area for a statistical 
analysis of the data records to be compressed. The first (and typically the only) 
argument passed to DCX$ANALYZE_INIT is an integer variable to contain 
the context value. The data compression facility assigns a value to the context 
variable and associates the value with the created work area. Each time you 
want a record analyzed in that area, specify the associated context variable. You 
can analyze two or more files at once by creating a different work area for each 
file, giving each area a different context variable, and analyzing the records of 
each file in the appropriate work area. 

Condition Values Returned 

DCX$_INVITEM Error; invalid item code. The number of 

arguments specified in the call was incorrect 
(this number should be odd), or an unknown item 
code was specified. 

DCX$_NORMAL Successful completion. 

This routine also returns any condition values returned by LIB$GET_VM. 


Item Code 

DCX$C_LIST 


DCX$C_ONE_PASS 
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DCX$COMPRESS_DATA—Compress a Data Record 

The DCX$COMPRESS_DATA routine compresses a data record. You call this 
routine for each data record to be compressed. 


Format 


Returns 


DCX$COMPRESS_DATA context ,in_rec ,out_rec [,outJength] 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access read only 

mechanism by reference 

Value identifying the data stream that DCX$COMPRESS_DATA compresses. 
The context argument is the address of a longword containing this value. 
DCX$COMPRESS_INIT initializes the value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 

in_rec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Data record to be compressed. The in_rec argument is the address of the 
descriptor of the data record string. 

out_rec 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Data record that has been compressed. The out_rec argument is the address of 
the descriptor of the compressed record that LIB$COMPRESS_DATA returns. 
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out_length 

OpenVMS usage word_signed 
type word integer (signed) 

access write only 

mechanism by reference 

Length (in bytes) of the compressed data record. The outjength argument is 
the address of a word into which LIB$COMPRESS_DATA returns the length of 
the compressed data record. 


Description 

The DCX$COMPRESS_DATA routine compresses a data record. You call this 
routine for each data record to be compressed. As you compress each record, 
write the compressed record to the file containing the compression/expansion 
map. For each record, write the length of the record and substring string 
containing the record to the same file. See the COMPRESS DATA section in 
Example 5-1. 


Condition Values Returned 


DCX$_INVCTX 


DCX$_INVDATA 


DCX$_INVMAP 

DCX$_NORMAL 

DCX$_TRUNC 


Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 

Error. You specified the item value DCX$C_ 
BOUNDED in the DCX$ANALYZE_INIT routine 
and attempted to compress a data record (using 
DCX$COMPRESS_DATA) that was not presented 
for analysis (using DCX$ANALYZE_DATA). 
Specifying the DCX$C_BOUNDED item value 
means that you must analyze all data records 
that are to be compressed. 

Error; invalid map. The map argument was not 
specified correctly or the context area is invalid. 

Successful completion. 

Error. The compressed data record has been 
truncated because the out_rec descriptor did 
not specify enough memory to accommodate the 
record. 


This routine also returns any condition values returned by LIB$ANALYZE. 
SDESC_R2 and LIB$SCOPY_R_DX. 
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DCX$COMPRESS_DONE—Specify Compression Complete 

The DCX$COMPRESS_DONE routine deletes the context area and sets the 
context variable to zero. 


Format 

DCX$COMPRESS_DONE context 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

context 

OpenVMS usage context 
type longword (unsigned) 

access write only 

mechanism by reference 

Value identifying the data stream that DCX$COMPRESS_DONE deletes. 

The context argument is the address of a longword containing this value. 
DCX$COMPRESS_INIT writes the value into context; you should not modify 
its value. You can define multiple context arguments to identify multiple data 
streams that are processed simultaneously. 


Description 

The DCX$COMPRESS_DONE routine deletes the context area and sets the 
context variable to zero, thus undoing the work of the DCX$COMPRESS_INIT 
routine. You call DCX$COMPRESS_DONE when all data records have been 
compressed (using DCX$COMPRESS_DATA). After calling DCX$COMPRESS_ 
DONE, call LIB$FREE_VM to free the virtual memory that DCX$MAKE_MAP 
used for the compression/expansion function. 


Condition Values Returned 


DCX$_INVCTX Error. The context variable is invalid or the 

context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 

DCX$_NORMAL Successful completion. 

This routine also returns any condition values returned by LIB$FREE_VM. 
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DCX$COMPRESSJNIT 


DCX$COMPRESS_INIT—Initialize Compression Context 

The DCX$COMPRESS_INIT routine initializes the context area for the 
compression of data records. 


Format 

DCX$COMPRESSJNIT context ,map 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access write only 

mechanism by reference 

Value identifying the data stream that DCX$COMPRESS_INIT initializes. The 
context argument is the address of a longword containing this value. You should 
not modify the context value after DCX$COMPRESS_INIT initializes it. You 
can define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 

map 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

The function created by DCX$MAKE_MAP. The map argument is the address of 
the compression/expansion function’s virtual address. 

The map argument must remain at this address until data compression is 
completed and the context is deleted by means of a call to DCX$COMPRESS_ 
DONE. 


Description 

The DCX$COMPRESS_INIT routine initializes the context area for the 
compression of data records. 

You call the DCX$COMPRESS_INIT routine after the call to DCX$ANALYZE. 
DONE. 
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Condition Values Returned 

DCX$_INVMAP Error; invalid map. The map argument was not 

specified correctly, or the context area is invalid. 
DCX$_NORMAL Successful completion. 

This routine also returns any condition values returned by LIB$GET_VM and 
LIB$FREE_VM. 
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DCX$EXPAND_DATA—Expand a Compressed Data Record 

The DCX$EXPAND_DATA routine expands (or restores) a compressed data record 
to its original state. 


Format 

DCX$EXPAND_DATA context ,in_rec ,out_rec [,outJength] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access read only 

mechanism by reference 

Value identifying the data stream that DCX$EXPAND_DATA expands. 

The context argument is the address of a longword containing this value. 
DCX$EXPAND_INIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 

in_rec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Data record to be expanded. The in_rec argument is the address of the descriptor 
of the data record string. 

out_rec 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Data record that has been expanded. The out_rec argument is the address of the 
descriptor of the expanded record returned by DCX$EXPAND_DATA. 
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out_length 

OpenVMS usage word_signed 
type word integer (signed) 

access write only 

mechanism by reference 

Length (in bjd^es) of the expanded data record. The outjength argument is the 
address of a word into which DCX$EXPAND_DATA returns the length of the 
expanded data record. 


Description 

The DCX$EXPAND_DATA routine expands (or restores) a compressed data record 
to its original state. You call this routine for each data record to be expanded. 


Condition Values Returned 


DCX$_INVCTX 

DCX$_INVDATA 

DCX$_INVMAP 

DCX$_NORMAL 

DCX$_TRUNC 


Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 

Error. A compressed data record is invalid 
(probably truncated) and therefore cannot be 
expanded. 

Error; invalid map. The map argument was not 
specified correctly, or the context area is invalid. 

Successful completion. 

Warning. The expanded data record has been 
truncated because the out_rec descriptor did 
not specify enough memory to accommodate the 
record. 


This routine also returns any condition values returned by LIB$ANALYZE. 
SDESC_R2 and LIB$SCOPY_R_DX. 
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DCX$EXPAND_DONE 


DCX$EXPAND_DONE—Specify Expansion Complete 

The DCX$EXPAND_DONE routine deletes the context area and sets the context 
variable to zero. 


Format 

DCX$EXPAND_DONE context 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

context 

OpenVMS usage context 
type longword (unsigned) 

access write only 

mechanism by reference 

Value identifying the data stream that DCX$EXPAND_DONE deletes. The 
context argument is the address of a longword containing this value. 
DCX$EXPAND_INIT initializes this value; you should not modify it. You can 
define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 


Description 

The DCX$EXPAND_DONE routine deletes the context area and sets the context 
variable to zero, thus undoing the work of the DCX$EXPAND_INIT routine. You 
call DCX$EXPAND_DONE when all data records have been expanded (using 
DCX$EXPAND_DATA). 


Condition Values Returned 

DCX$_INVCTX Error. The context variable is invalid, or the 

context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 

DCX$NORMAL Successful completion. 

This routine also returns any condition values returned by LIB$FREE_VM. 
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DCX$EXPANDJNIT—Initialize Expansion Context 

The DCX$EXPAND_INIT routine initializes the context area for the expansion of 
data records. 


Format 

DCX$EXPANDJNIT context ,map 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access write only 

mechanism by reference 

Value identifying the data stream that DCX$EXPAND_INIT initializes. The 
context argument is the address of a longword containing this value. After 
DCX$EXPAND_INIT initializes this context value, you should not modify it. You 
can define multiple context arguments to identify multiple data streams that are 
processed simultaneously. 

map 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Compression/expansion function (created by DCX$MAKE_MAP). The map 
argument is the address of the compression/expansion function’s virtual address. 

The map argument must remain at this address until data expansion is 
completed and context is deleted by means of a call to DCX$EXPAND_DONE. 


Description 

The DCX$EXPAND_INIT routine initializes the context area for the expansion of 
data records. 

You call the DCX$EXPAND_INIT routine as the first step in the expansion (or 
restoration) of compressed data records to their original state. 

Before you call DCX$EXPAND_INIT, read the length of the compressed file from 
the compression/expansion function (the map). Invoke LIB$GET_VM to get the 
necessary amount of storage for the function. LIB$GET_VM returns the address 
of the first byte of the storage area. 
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Condition Values Returned 

DCX$_INVMAP Error; invalid map. The map argument was not 

specified correctly, or the context area is invalid. 
DCX$_NORMAL Successful completion. 

This routine also returns any condition values returned by LIB$GET_VM. 
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DCX$MAKE_MAP—Compute the Compression/Expansion Function 

The DCX$MAKE_MAP routine uses the statistical information gathered by 
DCX$ANALYZE_DATA to compute the compression/expansion function. 

Format 

DCX$MAKE_MAP context ,map_addr [,map_size] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access write only 

mechanism by reference 

Value identifying the data stream that DCX$MAKE_MAP maps. The context 
argument is the address of a longword containing this value. DCX$ANALYZE_ 
INIT initializes this value; you should not modify it. You can define multiple 
context arguments to identify multiple data streams that are processed 
simultaneously. 

map_addr 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Starting address of the compression/expansion function. The map_addr 
argument is the address of a longword into which DCX$MAKE_MAP stores 
the virtual address of the compression/expansion function. 

map_size 

OpenVMS usage longword_signed 
type longword (unsigned) 

access write only 

mechanism by reference 

Length of the compression/expansion function. The map_size argument is the 
address of the longword into which DCX$MAKE_MAP writes the length of the 
compression/expansion function. This is an optional argument. 
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Description 

The DCX$MAKE_MAP routine uses the statistical information gathered by 
DCX$ANALYZE_DATA to compute the compression/expansion function. In 
essence, this map is the algorithm used to shorten (or compress) the original data 
records as well as to expand the compressed records to their original form. 

The map must be available in memory when any data compression or 
expansion takes place; the address of the map is passed as an argument to 
the DCX$COMPRESS_INIT and DCX$EXPAND_INIT routines, which initialize 
the data compression and expansion procedures, respectively. 

The map is stored with the compressed data records, because the compressed 
data records are indecipherable without the map. When compressed data records 
have been expanded to their original state and no further compression is desired, 
you should delete the map using the LIB$FREE_VM routine. 

DCX requires that you submit data records for analysis and then call the 
DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code, 
you must again submit data records for analysis (in the same order) and call 
DCX$MAKE_MAP again; on the second iteration, DCX$MAKE_MAP returns the 
DCX$_NORMAL status code. 


Condition Values Returned 


DCX$_AGAIN 


DCX$_INVCTX 


DCX$_NORMAL 


Informational. The map has not been created 
and the map_addr and map_size arguments 
have not been written because further analysis is 
required. The data records must be analyzed 
(using DCX$ANALYZE_DATA) again, and 
DCX$MAKE_MAP must be called again before 
DCX$MAKE_MAP will create the map and 
return the DCX$_NORMAL status code. 

Error. The context variable is invalid, or the 
context area is invalid or corrupted. This may 
be caused by a failure to call the appropriate 
routine to initialize the context variable or by an 
application program error. 

Successful completion. 


This routine also returns any condition values returned by LIB$GET_VM and 
LIB$FREE_VM. 
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Routines 


This chapter describes callable DEC Text Processing Utility (DECTPU) routines. 
It describes the purpose of the DECTPU callable routines, the parameters for the 
routine call, and the primary status returns. The parameter in the call syntax 
represents the object that you pass to a DECTPU routine. Each parameter 
description lists the data type and the passing mechanism for the object. The 
data types are standard OpenVMS data types. The passing mechanism indicates 
how the parameter list is interpreted. 

6.1 Introduction to DECTPU Routines 

Callable DECTPU routines make DECTPU accessible from within other 
languages and applications supported by OpenVMS. DECTPU can be called 
from a program written in any language that generates calls using the OpenVMS 
Calling Standard. You can also call DECTPU from OpenVMS utilities, for 
example, the Mail utility. Callable DECTPU lets you perform text-processing 
functions within your program. 

Callable DECTPU consists of a set of callable routines that resides in the 
DECTPU shareable images. You access callable DECTPU by linking against 
the shareable images, which include the callable interface routine names and 
constants. As with the DCL-level DECTPU interface, you can use files for input 
to and output from callable DECTPU. You can also write your own routines for 
processing file input, output, and messages. 

This chapter is written for system programmers who are familiar with the 
following: 

• The OpenVMS Calling Standard 

• The OpenVMS Run-Time Library (RTL) 

• The precise manner in which data types are represented on a VAX processor 
or an AXP processor 

• The method for calling routines written in a language other than the one you 
are using for the main program 

The calling program must ensure that parameters passed to a called procedure, 
in this case DECTPU, are of the type and form that the DECTPU procedure 
accepts. 

The DECTPU routines described in this chapter return condition values 
indicating the routine’s completion status. When comparing a returned condition 
value with a test value, you should use the LIB$MATCH routine from the 
OpenVMS Run-Time Library. Do not test the condition value as if it were a 
simple integer. 
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6.1.1 Two Interfaces to Callable DECTPU 

There are two interfaces you can use to access callable DECTPU: the simplified 
callable interface and the full callable interface. 

6.1.1.1 Simplified Callable Interface 

The easiest way to use callable DECTPU is to use the simplified callable interface. 
DECTPU provides two alternative routines in its simplified callable interface. 
These routines in turn call additional routines that do the following: 

• Initialize the editor 

• Provide the editor with the parameters necessary for its operation 

• Control the editing session 

• Perform error handling 

When using the simplified callable interface, you can use the TPU$TPU routine 
to specify a command line for DECTPU, or you can call the TPU$EDIT routine 
to specify an input file and an output file. TPU$EDIT builds a command string 
that is then passed to the TPU$TPU routine. These two routines are described in 
detail in Section 6.2. 

If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls the simplified callable interface. You must 
do this because the simplified callable interface destroys all parse information 
obtained and stored before the simplified callable interface was called. 

6.1.1.2 Full Callable Interface 

To use the full callable interface, you have your program access the main callable 
DECTPU routines directly. These routines do the following: 

• Initialize the editor (TPU$INTIALIZE) 

• Execute DECTPU procedures (TPU$EXECUTE_INIFILE and 
TPU$EXECUTE_COMMAND) 

• Give control to the editor (TPU$CONTROL) 

• Terminate the editing session (TPU$CLEANUP) 

When using the full callable interface, you must provide values for certain 
parameters. In some cases, the values you supply are actually addresses for 
additional routines. For example, when you call TPU$INITIALIZE, you must 
include the address of a routine that specifies initialization options. Depending 
on your particular application, you might also have to write additional routines. 
For example, you might need to write routines for performing file operations, 
handling errors, and otherwise controlling the editing session. Callable DECTPU 
provides utility routines that can perform some of these tasks for you. These 
utility routines can do the following: 

• Parse the command line and build the item list used for initializing the editor 

• Handle file operations 

• Output error messages 

• Handle conditions 

If your application calls the DECwindows version of DECTPU, the application 
can call TPU$INITIALIZE only once. 
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Various topics relating to the full callable interface are discussed in the following 
sections: 

• Section 6.3 begins by briefly describing the interface. However, most of this 
section describes the main callable DECTPU routines (TPU$INITIALIZE, 
TPU$EXECUTE_INIFILE, TPU$CONTROL, TPU$EXECUTE_COMMAND, 
and TPU$CLEANUP). 

• Section 6.3.2 discusses additional routines that DECTPU provides for use 
with the full callable interface. 

• Section 6.3.3 deflnes the requirements for routines that you can write for use 
with the full callable interface. 

The full callable interface consists of the main callable DECTPU routines and the 
DECTPU utility routines. 

6.1.2 Shareable Image 

Whether you use the simplifled callable interface or the full callable interface, 
you access callable DECTPU by linking against the DECTPU shareable image. 
This image contains the routine names and constants available for use by an 
application. In addition, the sharable image provides the following symbols: 

• TPU$GL_VERSION—The version of the shareable image 

• TPU$GL_UPDATE—The update number of the shareable image 

• TPU$_FACILITY—The DECTPU facility code 

For more information about how to link to the shareable image TPUSHR.EXE, 
refer to the OpenVMS Programming Environment Manual. 

6.1.3 Passing Parameters to Callable DECTPU Routines 

Parameters are passed to callable DECTPU routines by reference or by descriptor. 
When the parameter is a routine, the parameter is passed by descriptor as a 
bound procedure value (BPV) data type. 

A bound procedure value is a two-longword entity in which the first longword 
contains a procedure value and the second longword is the environment value (see 
the following figure). The environment value is determined in a language-specific 
manner when the original bound procedure value is generated. When the bound 
procedure is called, the calling program loads the second longword into Rl. 


Name of Your Routine 
Environment 


ZK-4046-GE 


6.1.4 Error Handling 

When you use the simplifled callable interface, DECTPU establishes its own 
condition handler, TPU$HANDLER, to handle all errors. When you use the full 
callable interface, there are two ways to handle errors: 

• You can use the DECTPU default condition handler, TPU$HANDLER. 

• You can write your own condition handler to process some of the errors and 
call TPU$HANDLER to process the rest. 
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The default condition handler, TPU$HANDLER, is described in Section 6.7. 
Information about writing your own condition handler can be found in the 
OpenVMS Programming Concepts Manual. 

6.1.5 Return Values 

All DECTPU condition codes are declared as universal symbols. Therefore, you 
automatically have access to these symbols when you link your program to the 
shareable image. The condition code values are returned in RO. Return codes 
for DECTPU can be found in the DEC Text Processing Utility Reference Manual. 
DECTPU return codes and their messages are accessible from the Help/Message 
facility. 

Additional information about condition codes is provided in the descriptions of 
callable DECTPU routines found in subsequent sections. This information is 
provided under the heading Condition Values Returned and indicates the values 
that are returned when the default condition handler is established. 

6.2 Simplified Callable Interface 

The DECTPU simplified callable interface consists of two routines: TPU$TPU 
and TPU$EDIT. These entry points to DECTPU are useful for the following kinds 
of applications: 

• Those able to specify all the editing parameters on a single command line 

• Those that need to specify only an input file and an output file 

If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls the simplified callable interface. You must 
do this because the simplified callable interface destroys all parse information 
obtained and stored before the simplified callable interface was called. 

The following example calls TPU$EDIT to edit text in the file INFILE.DAT and 
writes the result to OUTFILE.DAT. Note that the parameters to TPU$EDIT must 
be passed by descriptor. 

/* 

Sample C program that calls DECTPU. This program uses TPU$EDIT to 
provide the names of the input and output files 

*/ 

tinclude descrip 
int return_status; 

static $DESCRIPTOR (input_file, "infile.dat"); 
static $DESCRIPTOR (output_file, "outfile.dat"); 

main (argc, argv) 
int argc; 
char *argv[]; 

{ 

/* 

Call DECTPU to edit text in "infile.dat" and write the result 
to "outfile.dat". Return the condition code from DECTPU as the 
status of this program. 

*/ 

return_status = TPU$EDIT (&input_file, &output_file); 
exit (return_status); 

} 
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The next example performs the same task as the previous example. This time, 
the TPU$TPU entry point is used. TPU$TPU accepts a single argument which is 
a command string starting with the verb “TPU”. The command string can contain 
all of the qualifiers that are accepted by the EDIT/TPU command. 

/* 

Sample C program that calls DECTPU. This program uses TPU$TPU and 
specifies a command string 

*/ 

#include descrip 
int return_status; 

static $DESCRIPTOR (command prefix, "TPU/NOJOURNAL/NOCOMMAND/OUTPUT="); 
static $DESCRIPTOR (input_fTle, "infile.dat"); 
static $DESCRIPTOR (output_file, "outfile.dat"); 
static $DESCRIPTOR (space_desc, " "); 

char command^line [100]; 

static $DESCRIPTOR (command_desc, command_line); 

main (argc, argv) 
int argc; 
char *argv[]; 

{ 

/* 

Build the command line for DECTPU. Note that the command verb 
is "TPU" instead of "EDIT/TPU". The string we construct in the 
buffer command_line will be 

"TPU/NOJOURNAL/NOCOMMAND/OUTPUT=outfile.dat infile.dat" 

*/ 

return__status = STR$CONCAT (&command_desc, 

&command_prefix, 

&output_file, 

&space__desc, 

&input_file); 

if (! return__status) 

exit (return^status); 

/* 

Now call DECTPU to edit the file 

*/ 

return_status = TPU$TPU (&command__desc); 
exit (return_status); 

} 

The following section contains detailed information about the routines in the full 
DECTPU callable interface. If you use the simplified interface, that interface 
calls these routines for you. If you use the full interface, your code calls these 
routines directly. 

6.3 Full Callable Interface 

The DECTPU full callable interface consists of a set of routines that you can use 
to perform the following tasks: 

• Specify initialization parameters 

• Control file input/output 

• Specify commands to be executed by the editor 

• Control how conditions are handled 
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When you use the simplified callable interface, these operations are performed 
automatically. The individual DECTPU routines that perform these functions 
can be called from a user-written program and are known as the DECTPU full 
callable interface. This interface has two sets of routines: the main DECTPU 
callable routines and the DECTPU utility routines. These DECTPU routines, as 
well as your own routines that pass parameters to the DECTPU routines, are the 
mechanism that your application uses to control DECTPU. 

The following sections describe the main callable routines, how parameters are 
passed to these routines, the DECTPU utility routines, and the requirements of 
user-written routines. 

6.3.1 Main Callable DECTPU Utility Routines 

The following callable DECTPU routines are described in this chapter: 

• TPU$INITIALIZE 

• TPU$EXECUTE_INIFILE 

• TPU$CONTROL 

• TPU$EXECUTE_COMMAND 

• TPU$CLEANUP 


_ Note _ 

Before calling any of these routines, you must establish TPU$HANDLER 
or provide your own condition handler. See the routine description of 
TPU$HANDLER at the end of this chapter and the OpenVMS Calling 
Standard for information about establishing a condition handler. 


6.3.2 Other DECTPU Utility Routines 

The full callable interface includes several utility routines for which you can 

provide parameters. Depending on your application, you might be able to use 

these routines rather than write your own routines. These DECTPU utility 

routines and their descriptions follow: 

• TPU$CLIPARSE—Parses a command line and builds the item list for 
TPU$INITIALIZE 

• TPU$PARSEINFO—Parses a command and builds an item list for 
TPU$INITIALIZE 

• TPU$FILEIO—The default file I/O routine 

• TPU$MESSAGE—Writes error messages and strings using the built-in 
procedure MESSAGE 

• TPU$HANDLER—The default condition handler 

• TPU$CLOSE_TERMINAL—Closes the DECTPU channel to the terminal (and 
its associated mailbox) for the duration of a CALL_USER routine 

• TPU$SPECIFY_ASYNC_ACTION—Specifies an asynchronous event for 
interrupting the TPU$CONTROL routine 

• TPU$TRIGGER_ASYN_ACTION—Interrupts the TPU$CONTROL routine on 
a specified asynchronous event 
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Note that TPU$CLIPARSE and TPU$PARSEINFO destroy the context 
maintained by the CLI$ routines for parsing commands. 

6.3.3 User-Written Routines 

This section defines the requirements for user-written routines. When these 
routines are passed to DECTPU, they must be passed as bound procedure values. 
(See Section 6.1.3 for a description of bound procedure values.) Depending on 
your application, you might have to write one or all of the following routines: 

• Routine for initialization callback—This is a routine that TPU$INITIALIZE 
calls to obtain values for initialization parameters. The initialization 
parameters are returned as an item list. 

• Routine for file I/O—This is a routine that handles file operations. Instead 
of writing your own file I/O routine, you can use the TPU$FILEIO utility 
routine. DECTPU does not use this routine for journal file operations or for 
operations performed by the built-in procedure SAVE. 

• Routine for condition handling—This is a routine that handles error 
conditions. Instead of writing your own condition handler, you can use 
the default condition handler, TPU$HANDLER. 

• Routine for the built-in procedure CALL_USER—This is a routine that is 
called by the built-in procedure CALL_USER. You can use this mechanism to 
cause your program to get control during an editing session. 

6.4 Examples of Using DECTPU Routines 

Example 6—1, Example 6—2, Example 6—3, and Example 6—4 use callable 
DECTPU. These examples are included here for illustrative purposes only; 
Digital does not assume responsibility for supporting these examples. 

Example 6-1 Sample VAX BLISS Template for Callable DECTPU 

MODULE file_io_example (MAIN = top_level, 

ADDRESSING_MODE (EXTERNAL = GENERAL)) = 

BEGIN 

FORWARD ROUTINE 
top_level, 
tpu_init, 
tpu_io; 

I 

! Declare the stream data 

I 

MACRO 


stream_ 

file id = 

0, 

0, 

32, 

0 

% , 

! File ID 

stream' 

'rat = 

6, 

0, 

8, 

0 

% , 

! Record attributes 

stream' 

'rfm = 

7 , 

0, 

8, 

0 

% , 

! Record format 

stream] 

'file_nm = 

8, 

0, 

0, 

0 

% ; 

I File name descriptor 


! Main routine of this example 
! Initialize TPU 
! File I/O routine for TPU 

structure passed to the file I/O routine 


(continued on next page) 
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Example 6-1 (Cent.) Sample VAX BLISS Template for Callable DECTPU 


Declare the routines that would actually do the I/O. These must be supplied 
in another module 


EXTERNAL ROUTINE 
my_io_open, 
my__i enclose, 
my_io_get_record , 
my_io__put_record; 


! Routine to open a file 
I Routine to close a file 
! Routine to read a record 
! Routine to write a record 


I Declare the DECTPU routines 

! 

EXTERNAL ROUTINE 
tpu$fileio, 
tpu$handler, 
tpu$initialize, 
tpu$execute_inifile , 
tpu$execute_command, 
tpu$control, 
tpu$cleanup; 

I 

I Declare the DECTPU literals 

I 

EXTERNAL LITERAL 
tpu$k__close, 
tpu$k_close__delete, 
tpu$k_open, 
tpu$k__get, 
tpu$k__put, 

tpu$k_access, 

tpu$k_io, 

tpu$k_input, 

tpu$k_output, 

tpu$__calluser, 
tpu$_fileio, 
tpu$_outputfile, 
tpu$_sectionfile, 
tpu$_coinmandf ile, 
tpu$_filename, 
tpu$_journalfile, 
tpu$_options, 

tpu$m_recover, 

tpu$m__journal, 

tpu$m_read, 

tpu$m__command, 

tpu$m_create, 

tpu$m_section, 

tpu$m_display, 

tpu$m_output, 

tpu$m_reset__terminal, 
tpu$m_kill_processes, 
tpu$m_delete exith, 
tpu$m_last_tTme, 


! DECTPU's internal file I/O routine 
! DECTPU's condition handler 
! Initialize DECTPU 
! Execute the initial procedures 
! Execute a DECTPU statement 
! Let user interact with DECTPU 
! Have DECTPU cleanup after itself 


I File I/O operation codes 


! File access codes 


! Item list entry codes 


! Mask for values in options bitvector 


! Masks for cleanup bitvector 


(continued on next page) 
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Example 6-1 (Cent.) Sample VAX BLISS Template for Callable DECTPU 

tpu$_nofileaccess, I DECTPU status codes 

tpu$_openin, 

tpu$_inviocode, 

tpu$_failure, 

tpu$_closein, 

tpu$_closeout, 

tpu$_readerr, 

tpu$_writeerr, 

tpu$_success; 

ROUTINE top_level = 

BEGIN 

I++ 

! Main entry point of your program 

I_ 

! Your_initialization_routine must be declared as a BPV 
LOCAL 

initialize_bpv; VECTOR [2], 
status, 

cleanup_flags; 

I 

! First establish the condition handler 

I 

ENABLE 

tpu$handler (); 

! 

! Initialize the editing session, passing TPU$INITIALIZE the address of 
! the bound procedure value which defines the routine which DECTPU is 
I to call to return the initialization item list 

I 

initialize_bpv [0] = tpu_init; 
initialize_bpv [1] = 0; 
tpu$initialize (initialize_bpv); 

I 

! Call DECTPU to execute the contents of the command file, the debug file 
! or the TPU$INIT__PROCEDURE from the section file. 

I 

tpu$execute__inifile(); 

i 

! Let DECTPU take over. 

I 

tpu$control(); 

I 

! Have DECTPU cleanup after itself 

I 

cleanup^flags = tpu$m_reset__terminal OR 
tpu$m_kill__processes OR 
tpu$m_delete exith OR 
tpu$m_last_tTme; 

tpu$cleanup (cleanup_flags); 

RETURN tpu$_success; 

END; 


! Reset the terminal 
! Delete Subprocesses 
! Delete the exit handler 
! Last time calling the editor 


(continued on next page) 
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Example 6-1 (Cent.) Sample VAX BLISS Template for Callable DECTPU 

ROUTINE tpu_init = 

BEGIN 

I 

i Allocate the storage block needed to pass the file I/O routine as a 
! bound procedure variable as well as the bitvector for the initialization 
! options 

I 

OWN 

file__io_bpv: VECTOR [ 2 , LONG] 

INITIAL (TPU__IO, 0), 

options; 

I 

! These macros define the file names passed to DECTPU 

I 

MACRO 

OUt_file = 'OUTPUT.TPU' % , 
com__file = 'TPU$COMMAND' % , 
sec_file = 'TPU$SECTION' % , 
inp_file = 'FILE.TPU' % ; 


Create the item list to pass to DECTPU. Each item list entry consists of 
two words which specify the size of the item and its code, the address of 
the buffer containing the data, and a longword to receive a result (always 
zero, since DECTPU does not return any result values in the item list) 

+ - -—--— 

I Item Code | Item Length 

+ - + - 

I Buffer Address 

+ ----- 

I Return Address (always 0) 


! Remember that the item list is always terminated with a longword containing 
! a zero 

I 

BIND 

item_list = UPLIT BYTE ( 

WORD (4), 

WORD (tpu$_options), 

LONG (options), 

LONG (0), 

WORD (4), 

WORD (tpu$_fileio), 

LONG (file__io_bpv), 

LONG (0), 

WORD (%CHARCOUNT (out_file)), ! Output file 
WORD (tpu$_outputfile), 

LONG (UPLIT (%ASCII out^file)), 

LONG (0), 

WORD (%CHARCOUNT (com_file)), ! Command file 
WORD (tpu$__commandf ile), 

LONG (UPLIT (%ASCII com^file)), 

LONG (0), 


1 Options bitvector 


! File I/O routine 


.+ 

I 

■+ 

■+ 

I 

•+ 


(continued on next page) 
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Example 6-1 (Cent.) Sample VAX BLISS Template for Callable DECTPU 

WORD {%CHARCOUNT (sec_file)), ! Section file 
WORD (tpu$_sectionfile), 

LONG (UPLIT (%ASCII sec_file)), 

LONG (0), 

WORD (%CHARCOUNT (inp_file)), ! Input file 
WORD (tpu$_filename), 

LONG (UPLIT (%ASCII inp_file)), 

LONG (0), 

LONG (0)); I Terminating longword of 0 

I 

! Initialize the options bitvector 

I 

options = tpu$m_display OR ! We have a display 

tpu$m_section OR ! We have a section file 

tpu$m_create OR ! Create a new file if one does not 

! exist 

tpu$m_command OR I We have a section file 

tpu$m_output; I We supplied an output file spec 

I 

1 Return the item list as the value of this routine for DECTPU to interpret 

I 

RETURN item_list; 

END; 1 End of routine tpu_init 

ROUTINE tpu_io (p_opcode, stream: REF BLOCK [ ,byte], data) = 

I 

! This routine determines how to process a TPU I/O request 

I 

BEGIN 

LOCAL 

status; 

I 

1 Is this one of ours, or do we pass it to TPU's file I/O routines? 

I 

IF (..p_opcode NEQ tpu$k__open) AND (.stream [stream__file_id] GTR 511) 

THEN 

RETURN tpu$fileio (.p_opcode, .stream, .data); 

I 

! Either we're opening the file, or we know it's one of ours 
! Call the appropriate routine (not shown in this example) 

I 

SELECTONE ..p_opcode OF 
SET 

[tpu$k_open]: 

status = my_io_open (.stream, .data); 

[tpu$k_close, tpu$k_close_delete]: 

status = my_io_close (.stream, .data); 

[tpu$k_get]: 

status = my_io_get_record (.stream, .data); 

[tpu$k_put]: 

status = my_io_put_record (.stream, .data); 

[OTHERWISE]: 

status = tpu$_failure; 

TES; 


(continued on next page) 
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Example 6-1 (Cent.) Sample VAX BLISS Template for Callable DECTPU 

RETURN .status; 

END; ! End of routine TPU_IO 

END ! End Module file_io_exaiiiple 

ELUDOM 


Example 6-2 Normal DECTPU Setup in DEC Fortran 

C A sample FORTRAN program that calls DECTPU to act 

C normally, using the programmable interface. 

C 

C IMPLICIT NONE 

INTEGER*4 CLEAN_OPT 

INTEGER*4 STATUS 

INTEGER*4 BPV_PARSE(2) 

INTEGER*4 LOC_PARSE 

C declare the DECTPU functions 

INTEGER*4 TPU$CONTROL 

INTEGER*4 TPU$CLEANUP 

INTEGER*4 TPU$EXECUTE_INIFILE 

INTEGER*4 TPU$INITIALIZE 

INTEGER*4 TPU$CLIPARSE 

C declare a local copy to hold the values of DECTPU cleanup variables 

INTEGER*4 RESET_TERMINAL 

INTEGER*4 DELETE_JOURNAL 

INTEGER* 4 DELETE_BUFFERS,DELETE_WINDOWS 

INTEGER*4 DELETE_EXITH,EXECUTE_PROC 

INTEGER* 4 PRUNE_CACHE,KILL_PROCESSES 

INTEGER*4 CLOSE_SECTION 

C declare the DECTPU functions used as external 

EXTERNAL TPU$HANDLER 

EXTERNAL TPU$CLIPARSE 

EXTERNAL TPU$_SUCCESS !external error message 

EXTERNAL LOC_PARSE luser supplied routine to 

C call TPUCLIPARSE and setup 

C declare the DECTPU cleanup variables as external these are the 

C external literals that hold the value of the options 

EXTERNAL TPU$M_RESET_TERMINAL 

EXTERNAL TPU$M_DELETE_JOURNAL 

EXTERNAL TPU$M_DELETE_BUFFERS,TPU$M_DELETE_WINDOWS 

EXTERNAL TPU$M_DELETE_EXITH,TPU$M_EXECUTE_PROC 

EXTERNAL TPU$M_PRUNE_CACHE,TPU$M_KILL_PROCESSES 

100 CALL LIB$ESTABLISH ( TPU$HANDLER ) 'establish the condition handler 

C set up the Bound Procedure Value for the call to TPU$INITIALIZE 

BPV_PARSE( 1 ) = %LOC( LOC_PARSE ) 

BPV PARSE( 2 ) = 0 


(continued on next page) 


!options for clean up routine 
!return status from DECTPU routines 
!set up a Bound Procedure Value 
!a local function call 
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Example 6-2 (Cent.) Normal DECTPU Setup in DEC Fortran 

C call the DECTPU initialization routine to do some set up work 

STATUS = TPU$INITIALIZE { BPV_PARSE ) 

C Check the status if it is not a success then signal the error 

IF ( STATUS .NE. %LOC ( TPU$_SUCCESS ) ) THEN 

CALL LIB$SIGNAL( %VAL( STATUS ) ) 

GOTO 9999 


ENDIF 

execute the TPU$_ init files and also a command file if it 
was specified in the command line call to DECTPU 

STATUS = TPU$EXECUTE_INIFILE ( ) 

IF ( STATUS .NE. %LOC ( TPU$_SUCCESS ) ) THEN !make sure everything is ok 

CALL LIB$SIGNAL( %VAL( STATUS ) ) 

GOTO 9999 


ENDIF 

invoke the editor as it normally would appear 

STATUS = TPU$CONTROL ( ) Icall the DECTPU editor 


IF ( STATUS .NE. %LOC ( TPU$_SUCCESS ) ) THEN !make sure everything is ok 

CALL LIB$SIGNAL( %VAL( STATUS ) ) 

GOTO 9999 

ENDIF 

Get the value of the option from the external literals. In FORTRAN you 
cannot use external literals directly so you must first get the value 
of the literal from its external location. Here we are getting the 
values of the options that we want to use in the call to TPU$CLEANUP. 


DELETE_JOURNAL = %LOC ( TPU$M_DELETE_JOURNAL ) 

DELETE_EXITH = %LOC ( TPU$M_DELETE_EXITH ) 

DELETE_BUFFERS = %LOC ( TPU$M_DELETE_BUFFERS ) 

DELETE_WINDOWS = %LOC ( TPU$M_DELETE_WINDOWS ) 

EXECUTE_PROC = %LOC ( TPU$M_EXECUTE_PROC ) 

RESET_TERMINAL = %LOC ( TPU$M_RESET_TERMINAL ) 

KILL_PROCESSES = %LOC ( TPU$M_KILL_PROCESSES ) 

CLOSE_SECTION = %LOC { TPU$M CLOSE_SECTION ) 

Now that we have the local copies of the variables we can do the 
logical OR to set the multiple options that we need. 


CLEAN_OPT = DELETE_JOURNAL .OR. DELETE_EXITH .OR. 

1 DELETE_BUFFERS .OR. DELETE_WINDOWS .OR. EXECUTE_PROC 

1 .OR. RESET_TERMINAL .OR. KILL_PROCESSES .OR. CLOSE_SECTION 

do the necessary clean up 

TPU$CLEANUP wants the address of the flags as the parameter so 
pass the %LOC of CLEAN_OPT which is the address of the variable 

STATUS = TPUSCLEANUP ( %LOC ( CLEAN_OPT ) ) 

IF ( STATUS .NE. %LOC (TPU$_SUCCESS) ) THEN 

CALL LIB$SIGNAL{ %VAL(STATUS) ) 


ENDIF 

9999 CALL LIB$REVERT !go back to normal processing — handlers 

STOP 

END 


(continued on next page) 
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Example 6-2 (Cent.) Normal DECTPU Setup In DEC Fortran 

c 

c 

INTEGER*4 FUNCTION LOC_PARSE 

INTEGER*4 BPV(2) !A local Bound Procedure Value 

CHARACTER*12 EDIT_COMM !A command line to send to TPU$CLIPARSE 

C Declare the DECTPU functions used 

INTEGER*4 TPU$FILEIO 

INTEGER*4 TPU$CLIPARSE 

C Declare this routine as external because it is never called directly and 

C we need to tell FORTRAN that it is a function and not a variable 

EXTERNAL TPU$FILEIO 

BPV(l) = %LOC(TPU$FILEIO) !set up the BOUND PROCEDURE VALUE 

BPV(2) = 0 

EDIT_C0MM(1:12) = 'TPU TEST.TXT' 

C parse the command line and build the item list for TPU$INITIALIZE 

9999 LOC_PARSE = TPU$CLIPARSE (EDIT^COMM, BPV , 0) 

RETURN 

END 


Example 6-3 Building a Callback Item List with DEC Fortran 


c 

c 

c 

c 


c 

c 

c 


c 

c 

c 

c 

c 

c 


PROGRAM TEST__TPU 
IMPLICIT NONE 


Define the expected DECTPU return statuses 


EXTERNAL TPU$_SUCCESS 

EXTERNAL TPU$_QUITTING 

EXTERNAL TPU$_EXITING 

Declare the DECTPU routines and symbols used 


EXTERNAL 
EXTERNAL 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 


TPU$M_DELETE_CONTEXT 

TPU$HANDLER 

TPU$M_DELETE__CONTEXT 

TPU$INITIALIZE 

TPU$EXECUTE_INIFILE 

TPU$CONTROL 

TPU$CLEANUP 


Use LIB$MATCH_COND to compare condition codes 
INTEGER*4 LIB$MATCH_COND 

Declare the external callback routine 


EXTERNAL TPU_STARTUP ! the DECTPU set-up function 

INTEGER*4 TPU STARTUP 


INTEGER*4 BPV(2) 


Set up a bound procedure value 


(continued on next page) 
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Example 6-3 (Cent.) Building a Callback Item List with DEC Fortran 


Declare the functions used for working with the condition handler 

INTEGER*4 LIB$ESTABLISH 

INTEGER*4 LIB$REVERT 

Local Flags and Indices 

INTEGER*4 CLEANUP_FLAG ! flag(s) for DECTPU cleanup 

INTEGER*4 RET_STATUS 

INTEGER*4 MATCH_STATUS 

Initializations 

RET_STATUS = 0 

CLEANUP_FLAG = %LOC(TPU$M_DELETE_CONTEXT) 

Establish the default DECTPU condition handler 
CALL LIB$ESTABLISH(%REF{TPU$HANDLER)) 

Set up the bound procedure value for the initialization callback 

BPV(l) = %LOC (TPU_STARTUP) 

BPV(2) = 0 

Call the DECTPU procedure for initialization 

RET_STATUS = TPU$INITIALIZE(BPV) 

IF (RET_STATUS .NE. %LOC(TPU$_SUCCESS)) THEN 
CALL LIB$SIGNAL (%VAL(RET_STATUS)) 

ENDIF 

Execute the DECTPU initialization file 

RET_STATUS = TPU$EXECUTE_INIFILE() 

IF (RET_STATUS .NE. %LOC(TPU$_SUCCESS)) THEN 
CALL LIB$SIGNAL {%VAL(RET_STATUS)) 

ENDIF 

Pass control to DECTPU 
RET_STATUS = TPU$CONTROL() 

Test for valid exit condition codes. You must use LIB$MATCH_COND 
because the severity of TPU$_QUITTING can be set by the TPU 
application 

MATCH_STATUS = LIB$MATCH_COND (RET_STATUS, %LOC (TPU$_QUITTING), 

1 %LOC (TPU$_EXITING)) 

IF (MATCH_STATUS .EQ. 0) THEN 
CALL LIB$SIGNAL (%VAL(RET_STATUS)) 

ENDIF 


(continued on next page) 
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Example 6-3 (Cont.) Building a Callback Item List with DEC Fortran 


Clean up after processing 

RET_STATUS = TPU$CLEANUP( %REF(CLEANUP__FLAG) ) 

IF (RET_STATUS .NE. %LOC(TPU$_SUCCESS)) THEN 
CALL LIB$SIGNAL (%VAL(RET_STATUS)) 

ENDIF 

Set the condition handler back to the default 

RET_STATUS = LIB$REVERT() 

END 


INTEGER*4 FUNCTION TPU_STARTUP 
IMPLICIT NONE 

INTEGER*4 OPTION_MASK ! temporary variable for DECTPU 

CHARACTER*44 SECTION_NAME ! temporary variable for DECTPU 

External DECTPU routines and symbols 


EXTERNAL 
EXTERNAL 
EXTERNAL 
EXTERNAL 
EXTERNAL 
EXTERNAL 
EXTERNAL 
INTEGER*4 


TPU$K__OPTIONS 

TPU$M_READ 

TPU$M_SECTION 

TPU$M_DISPLAY 

TPU$K__SECTIONFILE 

TPU$K__FILEIO 

TPU$FILEIO 

TPU$FILEIO 


The bound procedure value used for setting up the file I/O routine 
INTEGER*4 BPV(2) 


Define the structure of the item list defined for the callback 


STRUCTURE 
INTEGER*2 
INTEGER*2 
INTEGER*4 
INTEGER*4 
END STRUCTURE 


/CALLBACK/ 

BUFFER_LENGTH 
ITEM_CODE 
BUFFER_ADDRESS 
RETURN ADDRESS 


There are a total of four items in the item list 


RECORD /CALLBACK/ CALLBACK (4) 

Make sure it is not optimized! 

VOLATILE /CALLBACK/ 

Define the options we want to use in the DECTPU session 

OPTION__MASK = %LOC(TPU$M_SECTION) .OR. %LOC(TPU$M_READ) 

1 .OR. %LOC(TPU$M_DISPLAY) 


(continued on next page) 
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Example 6-3 (Cent.) Building a Callback Item List with DEC Fortran 

c 

C Define the name of the initialization section file 

C 

SECTION_NAME = 'TPU$SECTION' 

C 

C Set up the required I/O routine. Use the DECTPU default. 

C 

BPV(l) = %LOC(TPU$FILEIO) 

BPV(2) = 0 
C 

C Build the callback item list 

C 

C Set up the edit session options 

C 

CALLBACK(l).ITEM_CODE = %LOC(TPU$K_OPTIONS) 

CALLBACK(l).BUFFER_ADDRESS = %LOC(OPTION_MASK) 

CALLBACK(l).BUFFER_LENGTH = 4 
CALLBACK(l).RETURN_ADDRESS = 0 
C 

C Identify the section file to be used 

C 

CALLBACK(2) .ITEM__CODE = %LOC(TPU$K__SECTIONFILE) 

CALLBACK (2 ) . BUFFER_ADDRESS = %LOC (SECTION__NAME) 

CALLBACK(2) .BUFFER__LENGTH = LEN(SECTION__NAME) 

CALLBACK(2).RETURN_ADDRESS = 0 
C 

C Set up the I/O handler 

C 

CALLBACK(3).ITEM_CODE = %LOC(TPU$K_FILEIO) 

CALLBACK(3).BUFFER_ADDRESS = %LOC(BPV) 

CALLBACK(3).BUFFER_LENGTH = 4 
CALLBACK(3).RETURN_ADDRESS = 0 
C 

C End the item list with zeros to indicate we are finished 

C 

CALLBACK(4).ITEM_CODE = 0 
CALLBACK(4).BUFFER_ADDRESS = 0 
CALLBACK(4).BUFFER_LENGTH = 0 
CALLBACK(4) .RETURN__ADDRESS = 0 
C 

C Return the address of the item list 

C 

TPU_STARTUP = %LOC(CALLBACK) 

RETURN 

END 


Example 6-4 Specifying a User-Written Fiie I/O Routine in VAX C 

/* 

Segment of a simple C program to invoke DECTPU. This program provides its 
own FILEIO routine instead of using the one provided by DECTPU. This program 
will run correctly if you write the routines it calls. 

*/ 

/* 

** To compile this example use the command: 

$ CC <file-name> 


(continued on next page) 
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Example 6-4 (Cent.) Specifying a User-Written File I/O Routine in VAX C 

** To link this example after a successful compilation: 

$ LINK <file“name>,sys$input/ 

SYS$LIBRARY:VAXCRTL/SHARE 

<PRESS-CTRL/Z> 

The TPUSHR sharable image is found by the linker in IMAGELIB.OLB. 

*/ 

linclude descrip 
tinclude stdio 

/* data structures needed */ 

struct bpv_arg /* bound procedure value */ 

{ 

int *routine__add ; /* pointer to routine */ 

int env ; /* environment pointer */ 

} ; 

struct item_list_entry /* item list data structure */ 

{ 

short int buffer_length; /* buffer length */ 

short int item_code; /* item code */ 

int *buffer_add; /* buffer address */ 

int *return_len__add; /* return address */ 

} ; 

struct stream_type 

{ 

int ident; /* stream id */ 

short int alloc; /* file size */ 

short int flags; /* file record attributes/format */ 

short int length; /* resultant file name length */ 

short int stuff; /* file name descriptor class & type */ 

int nam_add; /* file name descriptor text pointer */ 

} ; 

globalvalue tpu$_success; /* TPU Success code */ 

globalvalue tpu$_quitting; /* Exit code defined by TPU */ 

globalvalue /* Cleanup codes defined by TPU */ 

tpu$m_delete_journal, tpu$m_delete_exith, 

tpu$m_delete_buffers, tpu$m_delete windows, tpu$m_delete_cache, 
tpu$m_prune__cache, tpu$m_execute__fTle, tpu$m_execute_proc, 
tpu$m_delete_context, tpu$m_reset_terminal, tpu$m__kill processes, 
tpu$m_close__section, tpu$m_delete_others, tpu$m_last time; 
globalvalue /* Item codes for item iTst entries */ 

tpu$k_fileio, tpu$k_options, tpu$k_sectionfile, 
tpu$k_commandfile ; 

globalvalue /* Option codes for option item */ 

tpu$m_display, tpu$m_section, tpu$m_command, tpu$m_create ; 

globalvalue /* Possible item codes in item list */ 

tpu$k_access, tpu$k_filename, tpu$k__defaultfile, 
tpu$k_relatedfile, tpu$k record_attr, tpu$k__maximize_ver, 
tpu$k_flush, tpu$k_filesTze; 

globalvalue /* Possible access types for tpu$k_access */ 

tpu$k_io, tpu$k_input, tpu$k__output; 

globalvalue /* RMS File Not Found message code */ 

rms$_fnf; 

(continued on next page) 
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Example 6-4 (Cont.) Specifying a User-Written Fiie I/O Routine in VAX C 

globalvalue /* FILEIO routine functions */ 

tpu$k__open, tpu$k_close, tpu$k close delete, 
tpu$k_get, tpu$k_put; 
int lib$estabiish (); 
int tpu$cleanup (); 
int tpu$control (); 
int tpu$execute_inifile (); 
int tpu$handler (); 
int tpu$initialize (); 

/* 

This function opens a file for either read or write access, based upon 
the itemlist passed as the data parameter. Note that a full implementation 
of the file open routine would have to handle the default file, related 
file, record attribute, maximize version, flush and file size item code 
properly. 

*/ 

open__file (data, stream) 
int *data; 

struct stream_type *stream; 

{ 

struct item_list_entry *item; 

char *access; /* File access type */ 

char filename[256]; /* Max file specification size */ 

FILE *fopen(); 

/* Process the item list */ 


/* RTL routine to establish an event handler */ 
/* TPU routine to free resources used */ 

/* TPU routine to invoke the editor */ 

/* TPU routine to execute initialization code */ 
/* TPU signal handling routine */ 

/* TPU routine to initialize the editor */ 


item = data; 

while (item->item_code 1= 0 && item->buffer_length != 0) 

{ 

if (item->item_code == tpu$k_access) 

{ 

if (item->buffer_add == tpu$k_io) access = "r+"; 

else if (item->buffer_add == tpu$k_input) access = "r"; 

else if (item->buffer_add == tpu$k__output) access = "w"; 

} 

else if (item->item__code == tpu$k_filename) 

{ 

strncpy (filename, item->buffer_add, item->buffer_length); 
filename [item->buffer_length] = 0; 

lib$scopy_r_dx (&item->buffer_length, item->buffer^add, 

&stream->length); 


} 


else if 

(item->item code 

{ 


} 

else if 

(item->item code 

{ 


} 

else if 

(item->item code 

{ 


} 

else if 

(item->item_code 

{ 


} 

else if 

(item->item_code 

{ 



} 


tpu$k_defaultfile) 

/* Add code to handle default file 
/* spec here 
tpu$k_relatedfile) 

/* Add code to handle related 
/* file spec here 
tpu$k_record_attr) 

/* Add code to handle record 
/* attributes for creating files 
tpu$k__maximize__ver) 

/* Add code to maximize version 
/* number with existing file here 
tpu$k_flush) 

/* Add code to cause each record 
/* to be flushed to disk as written 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


(continued on next page) 
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Example 6-4 (Cont.) Specifying a User-Written Fiie I/O Routine in VAX C 

else if (item->item_code == tpu$k_filesize) 

{ /* Add code to handle specification */ 

} /* of initial file allocation here */ 

++item; /* get next item */ 

} 

stream->ident = fopen(filename,access); 
if (stream->ident != 0) 
return tpu$_success; 

else 

return rms$_fnf; 

} 

h 

This procedure closes a file 
*/ 

close_file (data,stream) 
struct stream_type *stream; 

{ 

close(stream->ident); 
return tpu$_success; 

} 

/* 

This procedure reads a line from a file 
*/ 

read_line(data,stream) 
struct dsc$descriptor *data; 
struct stream_type *stream; 

{ 

char textline[984]; /* max line size for TPU records */ 

int len; 

globalvalue rms$_eof; /* RMS End-Of-File code */ 

if (fgets(textline,984,stream->ident) == NULL) 
return rms$_eof; 

else 

{ 

len = strlen(textline); 
if (len > 0) 

len = len - 1; 

return lib$scopy_r_dx (&len, textline, data); 

} 

} 

/* 

This procedure writes a line to a file 
*/ 

write_line(data,stream) 
struct dsc$descriptor *data; 
struct stream_type *stream; 

{ 

char textline[984]; /* max line size for TPU records */ 

strncpy (textline, data->dsc$a_pointer, data->dsc$w_length); 
textline [data->dsc$w_length] = 0; 
fputs(textline,stream->ident); 
fputs("\n",stream->ident); 
return tpu$_success; 

> 


(continued on next page) 
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Example 6-4 (Cont.) Specifying a User-Written File I/O Routine in VAX C 

/* 

This procedure will handle I/O for TPU 

*/ 

fileio(code,stream,data) 
int *code; 
int *stream; 
int *data; 

{ 

int status; 

/* Dispatch based on code type. Note that a full implementation of the */ 

/* file I/O routines would have to handle the close and delete code properly */ 

/* instead of simply closing the file */ 

if (*code == tpu$k_open) /* Initial access to file */ 

status = open__file (data, stream); 

else if (*code == tpu$k_close) /* End access to file */ 

status = close_file (data,stream); 

else if (*code == tpu$k_close_delete) /* Treat same as close */ 

status = close_file (data,stream); 

else if (*code == tpu$k__get) /* Read a record from a file */ 

status = read_line (data,stream); 

else if (*code == tpu$k_put) /* Write a record to a file */ 

status = write_line (data,stream); 

else 

{ /* Who knows what we got? */ 

status = tpu$_success; 

printf ("Bad FILEIO I/O function requested"); 

} 

return status; 

} 

/* 

This procedure formats the initialization item list and returns it as 
its return value. 

*/ 

callrout() 

{ 

static struct bpv__arg add_block = 

{ fileio, 0 } ; /* BPV for fileio routine */ 

int options ; 

char *section__name = "TPU$SECTION"; 
static struct item_list_entry arg[] = 

{/* length code buffer add return add */ 

{ 4,tpu$k__fileio, 0, 0 }, 

{ 4,tpu$k_options, 0, 0 }, 

{ O,tpu$k_sectionfile,0, 0 }, 

{ 0 , 0 , 0 , 0 } 

}; 

/* Setup file I/O routine item entry */ 
arg[0].buffer_add = &add_block; 

/* Setup options item entry. Leave journaling off. */ 
options = tpu$m_display | tpu$m_section; 
arg[1].buffer^add = Soptions; 

/* Setup section file name */ 

arg[2] .buffer__length = strlen( section_name); 

arg[2 ] .buffer__add = section_name; 

return arg; 

} 

(continued on next page) 
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Example 6-4 (Cent.) Specifying a User-Written File I/O Routine in VAX C 

/* 

Main program. Initializes TPU, then passes control to it. 

*/ 

main() 

{ 

int return_status ; 
int cleanup_options; 
struct bpv^arg add_block; 

/* Establish as condition handler the normal DECTPU handler */ 

lib$establish(tpu$handler); 

/* Setup a BPV to point to the callback routine */ 

add_block.routine_add = callrout ; 
add_block.env = 0; 

/* Do the initialize of DECTPU */ 

return_status = tpu$initialize(&add_block); 
if (lreturn_status) 

exit(return_status); 

/* Have TPU execute the procedure TPU$INIT_PROCEDURE from the section file */ 
/* and then compile and execute the code from the command file */ 

return_status = tpu$execute_inifile(); 
if (!return_status) 

exit (return_status); 

/* Turn control over to DECTPU */ 

return_status = tpu$control (); 
if (lreturn_status) 

exit (return__status); 

/* Now clean up. */ 

cleanup^options = tpu$m_last_time | tpu$m delete_context; 
return_status = tpu$cleanup (&cleanup_optTons); 
exit (return_status); 

printf("Experiment complete"); 

} 


6.5 Creating and Calling a USER Routine 

This section describes the steps involved in creating an executeable image for 
the USER routine and how to call the routine from a C program in the DECTPU 
environment. The following list describes the steps in creating the executable 
image: 

1. Write a program in the appropriate high-level language; in the supporting 
example, the language is C. The program must contain a global routine 
named TPU$CALLUSER. 

2. Compile the program. 

3. Link the program with an options file to create a shareable image. 

4. Define the logical name TPU$CALLUSER to point to the file containing the 
USER routine. 

5. Invoke DECTPU. 
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6. From within a DECTPU session, call the high-level program to perform 
its function by specifying the built-in procedure CALL_USER with the 
appropriate parameters. The built-in procedure passes the specified 
parameters to the appropriate routine. 


6.5.1 The CALL_USER Code 

This is an example of a USER routine written in C. The comments in the code 
explain the various routine functions. 

/* call user.c */ 

/* 

A sample of a TPU CALL_USER routine written in C. 

The routine is compiled and linked as a shareable image and then the 
DCL logical TPU$CALLUSER is defined to point at the image. 

From within TPU, when the built-in CALL_USER is called, this image 
will be activated and the tpu$call_user routine will be called. 

This example is for VAX C but can be updated to work with DEC-C with little 
effort. 

*/ 

#include <descrip.h> 

extern int lib$sgetl_dd(), 
vaxc$crtl_init(); 

globalvalue 

tpu$_success; 

/* 

Because we know we are being called from a non-C based routine, call 
the CRTL initialization routine once 

*/ 

static int 

rtl inited = 0; 


extern int tpu$calluser ( 
int *int_param, 

struct dsc$descriptor *str_param, 
struct dsc$descriptor *result param ) 

/* 

A sample TPU CALL__USER routine that checks access to the file specified 
in the str_param descriptor. 

Return (in result_param): 

ACCESS - specified access is allowed 

NOACCESS - specified access is not allowed 
ERROR - Either invalid param or the file does not exist 
PARAM^ERROR - Invalid param passed 
MEMORY_ERROR - An error occured allocating memory 

An example from TPU code would be: 

file_access := CALL_USER (0, "SYS$LOGIN:LOGIN.COM"); 

I 

! Only look at the return value of ACCESS, 


IF file access = ' 

'ACCESS 

THEN 




file exists 

:= 1; 

ELSE 




file exists 

:= 0; 

ENDIF; 
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See the description of the CALL_USER built-in for more information on how to 
use the built-in. 


{ 

static char 
*error_str = "ERROR", 

*param_error__str = "PARAM_ERROR", 

*memory_error__str = "MEMORY_ERROR", 

*access_str = "ACCESS", 

*noaccess_str = "NOACCESS"; 
char 

*result__str__ptr; 
int 

result str length; 

/* 

If this is the first time in, call the VAXCRTL routine to init things 
*/ 

if (rtl_^inited == 0) { 
vaxc$crtl_J[nit(); 
rtl^inited = 1; 

} 

/* 

The integer must be between 0 and 7 for the 
call to the C RTL routine ACCESS 
*/ 

if ((*int__param < 0) || (*int_param >7)) { 
result__str__length = strlen (param___error_str); 
result__str_ptr = param_error_str; 

} 

else { 

/* 

If we were passed a null string, 
set the param error return value 

*/ 

if (str__param->dsc$w_length == 0) { 

result_str_length = strlen (param_error_str); 
result_str_ptr = param__error___str; 

} 

else { 

/* 

Because there is NO way of knowing if the descriptor we have 
been passed ends with a \0, we need to create a valid string 
pass to the rtl routine "access" 

*/ 

char 

*str ptr; 

/* 

Allocate memory enough for the string plus the null character 
*/ 

str_ptr = (char *) malloc (str_param->dsc$w_length + 1); 

/* 

Make sure the memory allocation worked... 

*/ 

if (str_ptr == 0) { 

result_str__length = strlen (memory__error_str); 
result_str_ptr = memory_error__str; 

} 
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else { 

/* 

Move the bytes from the descriptor into the memory 
pointed to by str_ptr, and end it with a \0 
Then call the access routine, free the memory 

*/ 

sprintf (str_ptr, "%.*s\0", str_param->dsc$w_length, 
str_param->dsc$a_pointer); 
if (access (str_ptr, *int_param) == 0) { 

result_str_length = strlen (access_str); 
result_str_ptr = access_str; 

} 

else { 

result_str_length = strlen (noaccess_str); 
result_str_ptr = noaccess^str; 

} 

free (str_ptr); 

} 

} 

} 

/* Setup the return descriptor */ 
lib$sgetl_dd (&result_str_length, result_param); 

/* 

Copy the result bytes into the descriptor's dynamic 
memory 
*/ 

memcpy (result_param->dsc$a_pointer, result_str__ptr, 
result_str_length); 

return tpu$_success; 

} 

Use the following command to compile the routine with the VAX C compiler: 

$ CC/LIST call_user.c 

6.5.2 Linking the CALL_USER Image 

To link the CALL_USER image as a shareable image requires a linker option file 
similar to the one that follows: 

! CALL_USER.OPT 
call_user.obj 
UNIVERSAL=TPU$CALLUSER 
SYS$LIBRARY:VAXCRTL/SHARE 

After you create the linker option file, use the following command to link the 
shareable image: 

$ LINK CALL_USER/OPT/SHARE/MAP/FULL 

This command produces a shareable image named CALL_USER.EXE. 

The description of the DECTPU built-in CALL_USER states that you must define 
the logical name TPU$CALLUSER to point to the image that contains the USER 
procedure. Use the following command to define the logical name: 

$ DEFINE TPU$CALLUSER SYS$DISK:[]CALL_USER.EXE 

If you move the image to another device and directory, you must appropriately 
revise the pointer. 
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6.6 Accessing the USER Routine from DECTPU 

To access the USER routine from DECTPU, your code must call the CALL_USER 
built-in procedure. The CALL_USER built-in procedure activates the sharable 
image pointed to by the logical name TPU$CALLUSER and calls the USER 
routine within that image. The following is an example of DECTPU code that can 
be used with the USER example routine in Section 6.5.1. 

! Module: CALL__USER.TPU - the access routine 

I 

! Constants used with the call to this procedure (or directly to the call_user 
! routine). 

I 

CONSTANT 

ACCESS_FILE_EXISTS := 0, 

ACCESS_FILE_EXECUTE := 1, 

ACCESS_FILE_WRITE := 2, 

ACCESS_FILE_DELETE := 2, 

ACCESS_FILE_READ := 4, 

ACCESS_FILE_EXE_DEL := ACCESS_FILE_EXECUTE + ACCESS_FILE_DELETE, 
ACCESS_FILE_EXE__WRITE := ACCESS__FILE__EXE_DEL, 

ACCESS_FILE_DEL_READ := ACCESS_FILE__DELETE + ACCESS_FILE__READ, 
ACCESS__FILE_DEL_WRITE := ACCESS_FILE_DEL__READ, 

ACCESS_FILE_EXE__READ := ACCESS_FILE_EXECUTE + ACCESS_FILE_READ; 


PROCEDURE access (val, the_file) 

I 

! Call the CRTL function ACCESS via the TPU CALL_USER built-in 

I 

! 0 = exists 

! 1 = execute 

! 2 = write (& delete) 

! 4 = read 

! (add them for combinations) 

! Return Values: 

I 1 = requested access is allowed 

! 0 = requested access is NOT allowed 
! -1 = an error occured with the built-in 
! Side Effects: 

! A message may end up in the message buffer if there is an error 

I 

LOCAL 

ret_val; 

! Handle the call___user errors 
ON_ERROR 

[TPU$_BADUSERDESC] : 

MESSAGE (ERROR_TEXT); 

RETURN -1; 

[TPU$_NOCALLUSER] : 

MESSAGE ("Could not find access call_user routine - check logicals"); 
RETURN -1; 

[TPU$__CALLUSERFAIL] : 

MESSAGE ("Something is wrong in the access call_user routine"); 
MESSAGE (ERROR__TEXT); 

RETURN -1 

[OTHERWISE] : 

MESSAGE (ERROR_TEXT); 

RETURN -1; 

ENDON_ERROR; 
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ret_val := CALL_USER (val, the_file); 

CASE ret_val 

["ACCESS"] ; 

RETURN 1; 

["NOACCESS"] : 

RETURN 0; 

[OUTRANGE] : 

MESSAGE ("Error with call to access routine: " + ret_val); 

ENDCASE; 

RETURN -1; 

ENDPROCEDURE; 

You can extend the EVE editor using the DECTPU code described at the 
beginning of this section. Copy the code to a file named CALL_USER.TPU in the 
current working directory and then execute the following commands: 

GET FILE CALL.USER.TPU 
EXTEND ALL 

To use the DECTPU routine ACCESS from EVE, write a DECTPU procedure 
EVE_EXISTS, coded as follows: 

PROCEDURE eve_exists (the_file) 

IF access (ACCESS_FILE_EXISTS, the_file) = 1 
THEN 

MESSAGE ("File " + the_file + " exists"); 

ELSE 

MESSAGE ("No such file " + the_file ); 

ENDIF; 

ENDPROCEDURE; 

This enables calls from the command line such as: 

Coimnand: exists sys$login:login.com 

This command directs that the message window indicate whether the file 
SYS$LOGIN:LOGIN.COM exists. 


6.7 DECTPU Routines 

The following pages describe the individual DECTPU routines. 
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TPU$CLEANUP—Free System Resources Used During DECTPU 

Session 

The TPU$CLEANUP routine cleans up internal data structures, frees memory, 
and restores terminals to their initial state. 

This is the final routine called in each interaction with DECTPU. 

Format 

TPU$CLEANUP flags 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under CONDITION 
VALUE RETURNED. 

Argument 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags (or mask) defining the cleanup options. The flags argument is the address 
of a longword bit mask defining the cleanup options or the address of a 32-bit 
mask defining the cleanup options. This mask is the logical OR of the fiag bits 
you want to set. Following are the various cleanup options. 

Symbol Function 

TPU$M_DELETE_JOURNAL Closes and deletes the journal file if it is open. 
TPU$M_DELETE_EXITH Deletes the DECTPU exit handler. 

TPU$M_DELETE_BUFFERS Deletes all text buffers. If this is not the 

last time you are calling DECTPU, then all 
variables referring to these data structures 
are reset, as if by the built-in procedure 
DELETE. If a buffer is deleted, then all 
ranges and markers within that buffer, and 
any subprocesses using that buffer, are also 
deleted. 

^The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field 
in which the bit is set. TPU$V_ is a bit number. 
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Symbol 

Function 

TPU$M_DELETE_WINDOWS 

Deletes all windows. If this is not the last 
time you are calling DECTPU, then all 
variables referring to these data structures 
are reset, as if by the built-in procedure 
DELETE. 

TPU$M_DELETE_CACHE 

Deletes the virtual file manager’s data 
structures and caches. If this deletion is 
requested, then all buffers are also deleted. If 
the cache is deleted, the initialization routine 
has to reinitialize the virtual file manager the 
next time it is called. 

TPU$M_PRUNE_CACHE 

Frees up any virtual file manager caches that 
have no pages allocated to buffers. This frees 
up any caches that may have been created 
during the session but are no longer needed. 

TPU$M_EXECUTE_FILE 

Reexecutes the command file if 
TPU$EXECUTE_INIFILE is called again. 

You must set this bit if you plan to specify 
a new file name for the command file. This 
option is used in conjunction with the option 
bit passed to TPU$INITIALIZE indicating the 
presence of the /COMMAND qualifier. 

TPU$M_EXECUTE_PROC 

Looks up TPU$INIT_PROCEDURE and 
executes it the next time TPU$EXECUTE 
INIFILE is called. 

TPU$M_DELETE_CONTEXT 

Deletes the entire context of DECTPU. If this 
option is specified, then all other options are 
implied, except for executing the initialization 
file and initialization procedure. 

TPU$M_RESET_TERMINAL 

Resets the terminal to the state it was in 
upon entry to DECTPU. The terminal mailbox 
and all windows are deleted. If the terminal 
is reset, then it is reinitialized the next time 
TPU$INITIALIZE is called. 

TPU$M_KILL_PROCESSES 

Deletes all subprocesses created during the 
session. 


^The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field 
in which the bit is set. TPU$V_ is a bit number. 
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Symbol Function 

TPU$M_CLOSE_SECTION^ Closes the section file and releases the 

associated memory. All buffers, windows, 
and processes are deleted. The cache is 
purged and the flags are set for reexecution 
of the initialization file and initialization 
procedure. If the section is closed and if 
the option bit indicates the presence of the 
SECTION qualifier, then the next call to 
TPU$INITIALIZE attempts a new restore 
operation. 

TPU$M_DELETE_OTHERS Deletes all miscellaneous preallocated data 

structures. Memory for these data structures 
is reallocated the next time TPU$INITIALIZE 
is called. 

TPU$M_LAST_TIME This bit should be set only when you are 

calling DECTPU for the last time. Note that 
if you set this bit and then recall DECTPU, 
the results are unpredictable. 

^The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field 
in which the bit is set. TPU$V_ is a bit number. 

^Using the simplified callable interface does not set TPU$_CLOSE_SECTION. This feature allows you 
to make multiple calls to TPU$TPU without requiring you to open and close the section file on each 
call. 


Description 

The cleanup routine is the final routine called in each interaction with DECTPU. 
It tells DECTPU to clean up its internal data structures and prepare for 
additional invocations. You can control what is reset by this routine by setting or 
clearing the flags described previously. 

When you finish with DECTPU, call this routine to free the memory and restore 
the characteristics of the terminal to their original settings. 

If you intend to exit after calling TPU$CLEANUP, do not delete the data 
structures; the operating system does this automatically. Allowing the operating 
system to delete the structures improves the performance of your program. 

Notes 

1. When you use the simplified interface, DECTPU automatically sets the 
following flags: 

• TPU$V_RESET_TERMINAL 

• TPU$V_DELETE_BUFFERS 

• TPU$V_DELETE_ JOURNAL 

• TPU$V_DELETE_WINDOWS 

• TPU$V_DELETE_EXITH 
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• TPU$V_EXECUTE_PROC 

• TPU$V_EXECUTE_FILE 

• TPU$V_PRUNE_CACHE 

• TPU$V_KILL_PROCESSES 

2. If this routine does not return a success status, no other calls to the editor 
should be made. 

Condition Value Returned 

TPU$_SUCCESS Normal successful completion. 
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TPU$CLIPARSE—Parse a Command Line 

The TPU$CLIPARSE routine parses a command line and builds the item list for 
TPU$INITIALIZE. 


Format 

TPU$CLIPARSE string ,fileio ,calLuser 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


itemjist 

longword (unsigned) 
read only 
by reference 


This routine returns the address of an item list. 


Arguments 

string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Command line. The string argument is the address of a descriptor of a DECTPU 
command. 


fileio 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_unsigned 
bound procedure value 
read only 
by descriptor 


File I/O routine. The fileio argument is the address of a descriptor of a file I/O 
routine. 


calLuser 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_unsigned 
bound procedure value 
read only 
by descriptor 


Call-user routine. The call_user argument is the address of a descriptor of a 
call-user routine. 


Description 

This routine calls CLI$DCL_PARSE to establish a command table and a 
command to parse. It then calls TPU$PARSEINFO to build an item list for 
TPU$INITIALIZE. 
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If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls TPU$CLIPARSE. You must do this 
because TPU$CLIPARSE destroys all parse information obtained and stored 
before TPU$CLIPARSE was called. 
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TPU$CLOSE_TERMINAL—Close Channel to Terminal 

The TPU$CLOSE_TERMINAL routine closes the DECTPU channel to the 
terminal. 


Format 

TPU$CLOSE_TERMINAL 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under CONDITION 
VALUE RETURNED. 

Arguments 

None. 

Description 

This routine is used with the built-in procedure CALL_USER and its associated 
call-user routine to control the DECTPU access to the terminal. When a call-user 
routine invokes TPU$CLOSE_TERMINAL, DECTPU closes its channel to the 
terminal and the channel of the DECTPU associated mailbox. 

When the call-user routine returns control to it, DECTPU automatically reopens 
a channel to the terminal and redisplays the visible windows. 

A call-user routine can use TPU$CLOSE_TERMINAL at any point in the 
program and as many times as necessary. If the terminal is already closed to 
DECTPU when TPU$CLOSE_TERMINAL is used, the call is ignored. 

Condition Value Returned 

TPU$_SUCCESS Normal successful completion. 
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TPU$CONTROL—Pass Control to DECTPU 

The TPU$CONTROL routine is the main processing routine of the DECTPU 
editor. It is responsible for reading the text and commands, and executing them. 
When you call this routine (after calling TPU$INITIALIZE), control is turned 
over to DECTPU. 


Format 

TPU$CONTROL [integer] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

integer 

OpenVMS usage integer 
type longword (unsigned) 

access read only 

mechanism by reference 

Prevents DECTPU from displaying the message “Editing session is not being 
journaled” when the calling program gives control to DECTPU. Specify a true 
(odd) integer to preserve compatibility in future releases. If you omit the 
parameter, DECTPU displays the message if journaling is not enabled. 

Description 

This routine controls the editing session. It is responsible for reading the text and 
commands and for executing them. Windows on the screen are updated to reflect 
the edits made. Your program can regain control by interrupting DECTPU using 
the TPU$SPECIFY_ASYN_ACTION routine, together with the TPU$TRIGGER_ 
ASYN_ACTION routine. 


_ Note _ 

Control is also returned to your program if an error occurs or when you 
enter either the built-in procedure QUIT or the built-in procedure EXIT. 
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Condition Values Returned 

TPU$_EXITING 

TPU$_NONANSICRT 

TPU$_QUITTING 

tpu$_recoverfail 


A result of EXIT (when the default condition 
handler is established). 

A result of operation termination — results when 
you call DECTPU with TPU$DISPLAYFILE 
set to nodisplay and you attempt to execute 
screen-oriented commands. 

A result of QUIT (when the default condition 
handler is established). 

A recovery operation was terminated abnormally. 
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TPU$EDIT—Edit a File 


The TPU$EDIT routine builds a command string from its parameters and passes 
it to the TPU$TPU routine. 

TPU$EDIT is another entry point to the DECTPU simplified callable interface. 


Format 

TPU$EDIT input ,output 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

input 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Input file name. The input argument is the address of a descriptor of a file 
specification. 

output 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Output file name. The output argument is the address of a descriptor of an 
output file specification. It is used with the /OUTPUT command qualifier. 


Description 

This routine builds a command string and passes it to TPU$TPU. If the length 
of the output descriptor is nonzero, then the /OUTPUT qualifier is added to 
the command string. The /OUTPUT qualifier causes a file to be written to the 
specified file even if no modifications are made to the input file. If the QUIT 
built-in is called, it prompts the user as if changes had been made to the buffer. 
This allows applications to check for the existence of the output file to see if the 
editing session was terminated, which is consistent with other OpenVMS callable 
editors. 

If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls TPU$EDIT. Your application must do this 
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because TPU$EDIT destroys all parse information obtained and stored before 
TPU$EDIT is called. 

Condition Values Returned 

This routine returns the same value as TPU$TPU. 
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TPU$EXECUTE_COMMAND—Execute One or More DECTPU 

Statements 

The TPU$EXECUTE_COMMAND routine allows your program to execute 
DECTPU statements. 


Format 

TPU$EXECUTE_COMMAND string 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by value 

DECTPU statement. The string argument is the address of a descriptor of a 
character string denoting one or more DECTPU statements. 


Description 

This routine performs the same function as the built-in procedure EXECUTE 
described in the DEC Text Processing Utility Reference Manual. 

Condition Values Returned 

TPU$_SUCCESS Normal successful completion. 

TPU$_EXITING EXIT built-in procedure was invoked. 

TPU$_QUITTING QUIT built-in procedure was invoked. 

TPU$_EXECUTEFAIL Execution aborted. This could be because of 

execution errors or compilation errors. 
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TPU$EXECUTE_INIFILE—Execute Initialization Files 

The TPU$EXECUTE_INIFILE routine allows you to execute a user-written 
initialization file. 

This routine must be executed after the editor is initialized and before any other 
commands are processed. 


Format 

TPU$EXECUTEJNIFILE 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

None. 


Description 

Calling the TPU$EXECUTE_INIFILE routine causes DECTPU to perform the 
following steps: 

1. The command file is read into a buffer. The default is TPU$COMMAND.TPU. 
If you specified a file on the command line that cannot be found, an error 
message is displayed and the routine is aborted. 

2. If you specified the /DEBUG qualifier on the command line, the DEBUG file 
is read into a buffer. The default is SYS$SHARE:TPU$DEBUG.TPU. 

3. The DEBUG file is compiled and executed (if available). 

4. TPU$INIT_PROCEDURE is executed (if available). 

5. The Command buffer is compiled and executed (if available). 

6. TPU$INIT_POSTPROCEDURE is executed (if available). 

_ Note _ 

If you call this routine after calling TPU$CLEANUP, you must set 
the flags TPU$_EXECUTEPROCEDURE and TPU$_EXECUTEFILE. 
Otherwise, the initialization file does not execute. 
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Condition Values Returned 

TPU$_SUCCESS 

TPU$_EXITING 

TPU$_QUITTING 

TPU$_COMPILEFAIL 

TPU$_EXECUTEFAIL 

TPU$_FAILURE 


Normal successful completion. 

A result of EXIT. If the default condition handler 
is being used, the session is terminated. 

A result of QUIT. If the default condition handler 
is being used, the session is terminated. 

The compilation of the initialization file was 
unsuccessful. 

The execution of the statements in the 
initialization file was unsuccessful. 

General code for all other errors. 


DECTPU-41 



DEC Text Processing Utility (DECTPU) Routines 
TPU$FILEIO 


TPU$FILEIO—Perform File Operations 

The TPU$FILEIO routine handles all DECTPU file operations. Your own file 
I/O routine can call this routine to perform some operations for it. However, the 
routine that opens the file must perform all operations for that file. For example, 
if TPU$FILEIO opens the file, it must also close it. 


Format 

TPU$FILEIO code ,stream ,data 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

code 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Item code specifying a DECTPU function. The code argument is the address of a 
longword containing an item code from DECTPU specifying a function to perform. 
Following are the item codes that you can specify in the file I/O routine: 

• TPU$K_OPEN—This item code specifies that the data parameter is the 
address of an item list. This item list contains the information necessary 
to open the file. The stream parameter should be filled in with a unique 
identifying value to be used for all future references to this file. The resultant 
file name should also be copied with a dynamic string descriptor. 

• TPU$K_CLOSE—The file specified by the stream argument is to be closed. 
All memory being used by its structures can be released. 

• TPU$K_CLOSE_DELETE—The file specified by the stream argument is 
to be closed and deleted. All memory being used by its structures can be 
released. 

• TPU$K_GET—The data parameter is the address of a dynamic string 
descriptor to be filled with the next record from the file specified by the 
stream argument. The routine should use the routines provided by the Run¬ 
Time Library to copy text into this descriptor. DECTPU frees the memory 
allocated for the data read when the file I/O routine indicates that the end of 
the file has been reached. 

• TPU$K_PUT—The data parameter is the address of a descriptor for the data 
to be written to the file specified by the stream argument. 
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Stream 

OpenVMS usage unspecified 
type longword (unsigned) 

access modify 

mechanism by reference 

File description. The stream argument is the address of a data structure 
consisting of four longwords. This data structure is used to describe the file to be 
manipulated. 

This data structure is used to refer to all files. It is written to when an open file 
request is made. All other requests use information in this structure to determine 
which file is being referenced. 

The following figure shows the stream data structure: 



File Identifier 

RFM 


Allocation 

Class 

Type 

Length 

Address of Name 


ZK-4045-GE 

The first longword is used to hold a unique identifier for each file. The user- 
written file I/O routine is restricted to values between 0 and 511. Thus, you can 
have up to 512 files open simultaneously. 

The second longword is divided into three fields. The low word is used to store 
the allocation quantity, that is, the number of blocks allocated to this file from 
the FAB (FAB$L_ALQ). This value is used later to calculate the output file size 
for preallocation of disk space. The low-order byte of the second word is used 
to store the record attribute byte (FAB$B_RAT) when an existing file is opened. 
The high-order byte is used to store the record format byte (FAB$B_RFM) when 
an existing file is opened. The values in the low word and the low-order and 
high-order bytes of the second word are used for creating the output file in the 
same format as the input file. These three fields are to be filled in by the routine 
opening the file. 

The last two longwords are used as a descriptor for the resultant or the expanded 
file name. This name is used later when DECTPU processes EXIT commands. 
This descriptor is to be filled in with the file name after an open operation. It 
should be allocated with either the routine LIB$SCOPY_R_DX or the routine 
LIB$SCOPY_DX from the Run-Time Library. This space is freed by DECTPU 
when it is no longer needed. 

data 

OpenVMS usage item_list_3 
type longword (unsigned) 

access modify 

mechanism by reference 

Stream data. The data argument is either the address of an item list or the 
address of a descriptor. 
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_ Note _ 

The meaning of this parameter depends on the item code specified in the 
code field. 


When the TPU$K_OPEN item code is issued, the data parameter is the address 
of an item list containing information about the open request. The following 
DECTPU item codes are available for specifying information about the open 
request: 

• TPU$K_ACCESS item code lets you specify one of three item codes in the 
buffer address field, as follows: 

- TPU$K_IO 

- TPU$K_INPUT 

- TPU$K_OUTPUT 

• TPU$K_FILENAME item code is used for specifying the address of a string 
to use as the name of the file you are opening. The length field contains the 
length of this string, and the address field contains the address. 

• TPU$K_DEFAULTFILE item code is used for assigning a default file name 
to the file being opened. The buffer length field contains the length, and the 
buffer address field contains the address of the default file name. 

• TPU$K_RELATEDFILE item code is used for specifying a related file name 
for the file being opened. The buffer length field contains the length, and the 
buffer address field contains the address of a string to use as the related file 
name. 

• TPU$K_RECORD_ATTR item code specifies that the buffer address field 
contains the value for the record attribute byte in the FAB (FAB$B_RAT) 
used for file creation. 

• TPU$K_RECORD_FORM item code specifies that the buffer address field 
contains the value for the record format byte in the FAB (FAB$B_RFM) used 
for file creation. 

• TPU$K_MAXIMIZE_VER item code specifies that the version number of the 
output file should be one higher than the highest existing version number. 

• TPU$K_FLUSH item code specifies that the file should have every record 
flushed after it is written. 

• TPU$K_FILESIZE item code is used for specifying a value to be used as the 
allocation quantity when creating the file. The value is specified in the buffer 
address field. 

Description 

By default, TPU$FILEIO creates variable-length files with carriage-return 
record attributes (fab$b_rfm = var, fab$b_rat = cr). If you pass to it the TPU$K_ 
RECORD_ATTR or TPU$K_RECORD_FORM item, that item is used instead. 

The following combinations of formats and attributes are acceptable: 
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Format 

Attributes 

STM,STMLF,STMCR 

VAR 

0,BLK,CR,BLK+CR 

o,blk,ftn,cr,blk+ftn,blk+cr 


All other combinations are converted to VAR format with CR attributes. 

This routine always puts values greater than 511 in the first longword of the 
stream data structure. Because a user-written file I/O routine is restricted to the 
values 0 through 511, you can easily distinguish the file control blocks (FCB) this 
routine fills in from the ones you created. 

_ Note _ 

DECTPU uses TPU$FILEIO by default when you use the simplified 
callable interface. When you use the full callable interface, you must 
explicitly invoke TPU$FILEIO or provide your own file I/O routine. 


Condition Values Returned 

The TPU$FILEIO routine returns an RMS status code to DECTPU. The file I/O 
routine is responsible for signaling all errors if any messages are desired. 
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TPU$FILE_PARSE— Parse the Given File Specification 

The TPU$FILE_PARSE routine provides a simplified interface to the $PARSE 
system service. DECTPU calls this routine when the built-in procedure FILE_ 
PARSE is executed from TPU code. 

Format 

TPU$FILE_PARSE result-string, flags, filespec, default-spec, related-spec 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
See Condition Values Returned. 

Arguments* 

result-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

This routine modifies the result-string to include the components of the filespec 
specified by the flags argument. The memory for the return string is allocated 
via the RTL routine LIB$SGET1_DD. Use the RTL routine LIB$SFREE1_DD to 
deallocate the memory for the return string. 

flags 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

The routine uses these flags to determine what filespec components should be 
returned. Table 6-1 shows the valid values for the flags argument. 

Table 6-1 TPU$FILE_PARSE Flags Argument 


Flag Bir 

Description 

TPU$M_NODE 

TPU$M_DEV 

TPU$M_DIR 

TPU$M_NAME 

TPU$M_TYPE 

Return the node component of the filespec. 

Return the device component of the filespec. 

Return the directory component of the filespec. 
Return the name component of the filespec. 

Return the type component of the filespec. 


^TPU$M . . . indicates a mask. There is a corresponding value for each mask in the form TPU$V . . . . 


(continued on next page) 
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Table 6-1 (Cent.) 

TPU$FILE_PARSE Flags Argument 

Flag Bit^ 

Description 

TPU$M_VER 

Return the version component of the filespec. 

TPU$M_HEAD 

Return NODE, DEVICE and DIRECTORY 
components of the filespec. If the TPU$M_NODE, 
TPU$M_DEV or TPU$M_DIR bits are set while 
TPU$M_HEAD is set, the routine signals the error 
TPU$_INCKWDCOM and returns control to the 
caller. 

TPU$M_TAIL 

Return NAME, TYPE and VERSION components 
of the filespec. If the TPU$M_NAME, TPU$M_ 
TYPE or TPU$M_VER bits are are set while 
TPU$M_TAIL is set, the routine signals the error 
TPU$_INCKWDCOM and returns control to the 
caller. 

^TPU$M . . . indicates 

a mask. There is a corresponding value for each mask in the form TPU$V .... 

filespec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 

The object file specification. 

default-spec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 

Contains the default file specification. The default file specification fields are used 
in the result string as substitutes for fields omitted in the filespec argument. You 
can also make substitutions in the result string using the related-spec argument. 

You may use the value 0 when no default-spec is to be applied to the file 

specification. 


related-spec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 


The related-spec contains the related file specification. The fields in the related 
file specification are substituted in the result-string if a particular field is missing 
from both the filespec and default-spec arguments. 

You may use the value 0 when no default-spec is to be applied to the file 
specification. 
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Description 

The TPU$FILE_PARSE routine returns the a string containing the fields 
requested of the file specified. The file is not required to exist when the parse 
is done. The intention of the TPU$FILE_PARSE routine is to construct a valid 
file specification from the information passed in through the file specification, the 
default file specification and the related file specification. 

The routine uses the VMS routine $PARSE to return the requested information. 

The TPU$FILE_PARSE routine is also called by DECTPU when the TPU built-in 
procedure FILE_PARSE is executed from TPU code. The return value of the 
built-in procedure is the string returned in the result-string argument. 

Condition Values Returned 


TPU$_SUCCESS 

TPU$_INCKWDCOM 

TPU$_PARSEFAIL 


Normal successful completion. If the return 
string contains a null-string, then the last match 
of the search operations has occurred. 

The fiags argument had an illegal combination of 
values. 

The parse failed. 
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TPU$FILE_SEARCH—Search File System for Specified File 

The TPU$FILE_SEARCH routine provides a simplified interface to the $SEARCH 
system service. DECTPU call this routine when TPU code executes the FILE_ 
SEARCH built-in procedure. 


Format 

TPU$FILE_SEARCH result-string, flags, filespec, default-spec, related-spec 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
See Condition Values Returned. 

Arguments 

result-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

This routine modifies the result-string to include the components of the filespec 
passed by the fiags argument. The memory for the return string is allocated via 
the RTL routine LIB$SGET1_DD. To deallocate memory for the string, use the 
RTL routine LIB$SFREE1_DD. 

flags 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

The routine uses these fiags to determine what filespec component(s) should be 
returned. Table 6-2 lists the valid flag values. 


Table 6-2 TPU$FILE_SEARCH Flags Argument 


Flag Bit^ 

Description 

TPU$M_NODE 

TPU$M_DEV 

TPU$M_DIR 

TPU$M_NAME 

TPU$M_TYPE 

Return the node component of the filespec. 

Return the device component of the filespec. 

Return the directory component of the filespec. 
Return the name component of the filespec. 

Return the type component of the filespec. 


^TPU$M . . . indicates a mask. There is a corresponding value for each mask in the form TPU$V . . . . 


(continued on next page) 
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Table 6-2 (Cent.) TPU$FILE_SEARCH Flags Argument 


Flag 

Description 

TPU$M_VER 

Return the version component of the filespec. 

TPU$M_REPARSE 

Reparse the filespec before processing. This is 
intended to be used to reset the file search. 

TPU$M_HEAD 

Return NODE, DEVICE and DIRECTORY 
components of the filespec. If the TPU$M_NODE, 
TPU$M_DEV or TPU$M_DIR bits are set while 
TPU$M_HEAD is set, the routine will signal the 
error TPU$_INCKWDCOM and return. 

TPU$M_TAIL 

Return NAME, TYPE and VERSION components 
of the filespec. If the TPU$M_NAME, TPU$M_ 
TYPE or TPU$M_VER bits are are set while 
TPU$M_TAIL is set, the routine will signal the 
error TPU$_INCKWDCOM and return. 

^TPU$M . . . indicates 8 

1 mask. There is a corresponding value for each mask in the form TPU$V . . . . 

filespec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 

Object file specification 

default-spec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 

The default file specification. The default file specification fields are use to fill 
in the result-string when fields are omitted in the filespec argument. Use the 
related-spec argument to specify other substitutions. 

You may use the value 0 when no default-spec is to be applied to the file 

specification. 


related-spec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 

Contains the related file specification. The fields in the related file specification 
are used in the result-string for fields omitted in the filespec and default-spec 

arguments. 


You may use the value 0 when no default-spec is to be applied to the file 


Specification. 
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Description 

This routine allows an application to verify the existence of, and return 
components of, a file specification. Wildcard operations are permitted. The 
routine uses the system service routines $PARSE and $SEARCH to seek the 
filespec. 

If no wildcards are included in the filespec string and the result-string returns 
a zero (0) length string, no file was found. If wildcard characters were present 
in the filespec and the result-string returns a zero (0) length string, there are no 
more files that match the wildcard(s). 

To find all the files that match a wildcard specification, repeatedly call this 
routine, passing the same arguments, until the routine returns a zero-length 
result string. 

The TPU$FILE_SEARCH routine is called by DECTPU when the TPU built-in 
procedure FILE_SEARCH is executed from TPU code. The return value of the 
built-in procedure is the string returned in the result-string argument. 


Condition Values Returned 

TPU$_SUCCESS 

TPU$_INCKWDCOM 

TPU$_PARSEFAIL 

TPU$_SEARCHFAIL 


Normal successful completion. If the return 
string contains a null-string, the final match 
operations was detected. 

The flags argument had an illegal combination of 
values. 

The requested repeat parse failed. 

An error occurred during the search operation. 
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TPU$HANDLER—DECTPU Condition Handler 

The TPU$HANDLER routine is the DECTPU condition handler. 

The DECTPU condition handler invokes the Put Message (SYS$PUTMSG) system 
service, passing it the address of TPU$MESSAGE. 


Format 


TPU$HANDLER signaLvector ,mechanism_vector 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. 


Arguments 

signaLvector 

OpenVMS usage arg_list 
type longword (unsigned) 

access modify 

mechanism by reference 

Signal vector. See the OpenVMS System Services Reference Manual for 
information about the signal vector passed to a condition handler. 

mechanism_vector 

OpenVMS usage arg_list 
type longword (unsigned) 

access read only 

mechanism by reference 

Mechanism vector. See the OpenVMS System Services Reference Manual for 
information about the mechanism vector passed to a condition handler. 


Description 

The TPU$MESSAGE routine performs the actual output of the message. The 
Put Message (SYS$PUTMSG) system service only formats the message. It gets 
the settings for the message flags and facility name from the variables described 
in Section 6.1.2. Those values can be modifled only by the DECTPU built-in 
procedure SET. 

If the condition value received by the handler has a FATAL status or does not 
have the DECTPU facility code, the condition is resignaled. 

If the condition is TPU$_QUITTING, TPU$_EXITING, or TPU$_RECOVERFAIL, 
a request to UNWIND is made to the establisher of the condition handler. 

After handling the message, the condition handler returns with a continue 
status. DECTPU error message requests are made by signaling a condition to 
indicate which message should be written out. The arguments in the signal 
array are a correctly formatted message argument vector. This vector sometimes 
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contains multiple conditions and formatted ASCII output (FAO) arguments for 
the associated messages. For example, if the editor attempts to open a file that 
does not exist, the DECTPU message TPU$_NOFILEACCESS is signaled. The 
FAO argument to this message is a string for the name of the file. This condition 
has an error status, followed by the OpenVMS RMS status field (STS) and status 
value field (STV). Because this condition does not have a fatal severity, the editor 
continues after handling the error. 

The editor does not automatically return from TPU$CONTROL. If you call the 
TPU$CONTROL routine, you must explicitly establish a way to regain control 
(for example, using the built-in procedure CALL_USER). If you establish your 
own condition handler but call the DECTPU handler for certain conditions, 
the default condition handler must be established at the point in your program 
where you want to return control. You can also interrupt TPU$CONTROL 
by having your program specify and then trigger an asynchronous routine via 
the TPU$SPECIFY_ASNYC_ACTION and TPU$TRIGGER_ASYNC_ACTION 
routines. 

See the OpenVMS Calling Standard for details on writing a condition handler. 
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TPU$INITIALIZE—Initialize DECTPU for Processing 

The TPU$INITIALIZE routine initializes DECTPU for text processing. This 
routine allocates global data structures, initializes global variables, and calls 
the appropriate setup routines for each of the major components of the editor, 
including the Screen Manager and the I/O subsystem. 


Format 


TPU$INITIALIZE callback [,user_arg] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


ARGUMENT 


callback 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_unsigned 
bound procedure value 
read only 
by descriptor 


Callback routine. The callback argument is the address of a user-written routine 
that returns the address of an item list containing initialization parameters or 
a routine for handling file I/O operations. This callback routine must call a 
command line parsing routine, which can be TPU$CLIPARSE or a user-written 
parsing routine. 


Callable DECTPU defines item codes that you can use to specify initialization 
parameters. The following rules must be followed when building the the item list: 

• If you use the TPU$_OTHER_FILENAMES item code, it must follow the 
TPU$_FILENAME item code. 

• If you use either the TPU$_CHAIN item code or or the TPU$_ENDLIST code, 
it must be the last item code in the list. 


The following figure shows the general format of an item descriptor. For 
information about how to build an item list, refer to the programmer’s manual 
associated with the language you are using. Any reference to command line 
qualifiers refer to those command line qualifiers that you use with the EDIT/TPU 
command. 


Item Code 


Buffer Length 


Buffer Address 


Return Address 


ZK-4044-GE 
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The return address in an item descriptor is usually 0. 
The following item codes are available: 


Item Code 


Description 


TPU$_OPTIONS 


TPU$_JOURNALFILE 


TPU$_SECTIONFILE 


TPU$_OUTPUTFILE 


TPU$_DISPLAYFILE 


TPU$_COMMANDFILE 


TPU$_FILENAME 


Enables the command qualifiers. The bits in the 
bit mask specified by the buffer address field 
correspond to the various DECTPU command 
qualifiers. 

Passes the string specified with the /JOURNAL 
qualifier. The buffer length field is the length 
of the string, and the buffer address field is the 
address of the string. This string is available 
with GET.INFO (COMMAND_LINE,"JOURNAL. 
FILE”). This string can be a null string. 

Passes the string that is the name of the binary 
initialization file (section file) to be mapped in. 

The buffer length field is the length of the string 
and the buffer address field is the address of the 
string. If the TPU$V_SECTION bit is set, this 
item code must be specified. 

Passes the string specified with the /OUTPUT 
qualifier. The buffer length field is the length 
of the string, and the buffer address field 
specifies the address of the string. This string 
is returned by the built-in procedure GET.INFO 
(COMMAND.LINE, “OUTPUT.FILE”). The string 
can be a null string. 

Passes the string specified with the /DISPLAY 
qualifier. The buffer length field defines the length 
of the string, and the buffer address field defines 
the string address. The interface between the 
TPUSHR image and the display file image is 
not documented so applications should only use 
this option with documented display files such as 
TPU$CCTSHR or TPU$MOTIFSHR. 

Passes the string specified with the /COMMAND 
qualifier. The buffer length field is the length 
of the string, and the buffer address field is the 
address of the string. This string is returned by 
the built-in procedure GET.INFO (COMMAND. 
LINE, “COMMAND.FILE”). The string can be a 
null string. 

Passes the string that is the name of the first 
input file specified on the command line. The 
buffer length field specifies the length of this 
string, and the buffer address field specifies its 
address. This string is returned by the built- 
in procedure GET.INFO (COMMAND.LINE, 
“FIRST.FILE.NAME”). This file name can be a 
null string. 
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Item Code 


TPU$_OTHER 

FILENAMES 


TPU$_FILEIO 


TPU$_CALLUSER 


TPU$_INIT_FILE 


TPU$_START_LINE 


Description 

Passes a string that contains the name of an 
input file that follows the first input file on the 
command line. The buffer length field specifies the 
length of this string, and the buffer address field 
specifies its address. Each additional file specified 
on the command line requires its own TPU$_ 
OTHER_FILENAMES item entry. These strings 
are returned by the GET_INFO (COMMAND_ 
LINE,“NEXT_FILE_NAME”) built-in procedure in 
the order they appear in the item list. This item 
code must appear after the TPU$_FILENAME 
item in the item list. 

Passes the bound procedure value of a routine 
to be used for handling file operations. You can 
provide your own file I/O routine, or you can 
call TPU$FILEIO, the utility routine provided 
by DECTPU for handling file operations. The 
buffer address field specifies the address of a two- 
longword vector. The first longword of the vector 
contains the address of the routine. The second 
longword specifies the environment value that 
DECTPU loads into R1 before calling the routine. 

Passes the bound procedure value of the user- 
written routine that the built-in procedure CALL_ 
USER is to call. The buffer address field specifies 
the address of a two-longword vector. The first 
longword of the vector contains the address of 
the routine. The second longword specifies the 
environment value that DECTPU loads into R1 
before calling the routine. 

Passes the string specified with the 
/INITIALIZATION qualifier. The buffer length 
field is the length of the string, and the buffer 
address field is the address of the string. This 
string is returned by the built-in procedure GET_ 
INFO (COMMAND_LINE,‘TNIT_FILE”). 

Passes the starting line number for the edit. 

The buffer address field contains the first of the 
two integer values you specified as part of the 
/START_POSITION command qualifier. The value 
is available using the built-in procedure GET_ 
INFO (COMMAND_LINE,“LINE”). Usually an 
initialization procedure uses this information to 
set the starting position in the main editing buffer. 
The first line in the buffer is line 1. 
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Item Code 


Description 


TPU$_START_CHAR 


TPU$_CHARACTERSET 


TPU$_WORKFILE 


TPU$_CHAIN 

TPU$_ENDLIST 

TPU$_PARENT_WIDGET 


TPU$_APPLICATION 

CONTEXT 


TPU$_DEFAULTSFILE 


Passes the starting column position for the edit. 
The buffer address field contains the second of 
the two integer values you specified as part of 
the /START_POSITION command qualifier. The 
value is available using the built-in procedure 
GET.INFO (COMMAND.LINE, “CHARACTER”). 
Usually an initialization procedure uses this 
information to set the starting position in the 
main editing buffer. The first column on a line to 
character 1. 

Passes the string specified with the character_ 
set qualifier. The buffer length field specifies 
the string length and the buffer address field 
specifies the string address. Valid strings are 
“DEC_MCS” (the default value), “ISO.LATINl”, 
and “GENERAL”. If the application tries to pass 
any other string, the routine signals an error and 
passes the default string (DEC_MCS). 

Passes the string specified with the AVORK 
qualifier. The buffer length field specifies the 
string length and the buffer address specifies the 
string address. This string is available with GET_ 
INFO (COMMAND_LINE, “WORK_FILE”). 

Passes the address of the next item list to the 
process specified by the buffer address field. 
Signals the end of the item list. 

Passes the appropriate parent widget when 
invoking the DECwindows version of the editor. 
This routine is not specified by the application; 
DECTPU invokes its own application shell. The 
widget address is passed in the buffer address 
field. This item code is only valid when using the 
DECwindows interface. 

Passes the application context to use with the 
TPU$_PARENT_WIDGET. DECTPU defaults to 
its own application context. The buffer address 
field specifies the application context address. 

This item code is only valid when using the 
DECwindows interface. 

Specifies which file DECTPU uses to initialize the 
X defaults database. The buffer length specifies 
the string length and the buffer address field 
specifies the string address. This item code is only 
valid when using the DECwindows interface. 
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Item Code 

Description 

TPU$_CTRL_C_ROUTINE 

Passes the bound procedure value of a routine 
to be used for handling Ctrl/C ASTs. DECTPU 
calls the routine when a Ctrl/C AST occurs. If 
the routine returns a FALSE value, DECTPU 
assumes that the Ctrl/C has been handled. If the 
routine returns a TRUE value, DECTPU aborts 
any currently executing DECTPU procedure. The 
buffer address field specifies the address of a two- 
longword vector. The first longword of the vector 
contains the address of the routine. The second 
longword specifies the environment value that 
DECTPU loads into R1 before calling the routine. 

TPU$_DEBUGFILE 

Passes the string specified with the /DEBUG 
command qualifier. The buffer length field is the 
length of the string, and the buffer address field is 
the address of the string. 

TPU$_FILE_SEARCH 

Passes the bound procedure value of a routine 
to be used to replace the TPU$FILE_SEARCH 
routine which is called when the built-in procedure 
FILE_SEARCH is called from TPU code. See the 
description of the TPU$FILE_SEARCH and the 
user routine FILE_SEARCH for more information. 

TPU$_FILE_PARSE 

Passes the bound procedure value of a routine 
to be used to replace the TPU$FILE_PARSE 
routine which is called when the built-in procedure 
FILE_PARSE is called from TPU code. See the 
description of the TPU$FILE_PARSE and the user 
routine FILE_PARSE for more information. 


Table 6—3 lists the bits and corresponding masks enabled by the item code 
TPU$K_OPTIONS and shows how each bit affects TPU$INITIALIZE operation. 
Several bits in the TPU$_OPTIONS mask require additional item code entries 
in the item list. An example of this is TPU$M_COMMAND which requires a 
TPU$_COMMANDFILE entry in the item list. 


Table 6-3 Valid Masks for the TPU$K_OPTIONS Item Code 


Mask^ 

GETJNFO 

Request String^ 

Description 

TPU$M_COMMAND 

COMMAND 

If DECTPU senses the presence of the TPU$_ 
COMMANDFILE item, it tries to read, compile 
and execute the unbound TPU code. 


^The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field in which the bit is 
set. TPU$V_ is a bit number. 

^Most bits in the mask have a corresponding GET_INFO (COMMAND_LINE) request string. 


(continued on next page) 
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Table 6-3 (Cent.) Valid Masks for the TPU$K_OPTIONS Item Code 


Mask^ 

GETJNFO 

Request String^ 

Description 

TPU$M_COMMAND_ 

DFLTED 

N/A 

Specifies DECTPU should use the default 
command file name of TPU$COMMAND.TPU 
when reading in the command file. No error is 
reported if the default command file is not found. 
TPU$INITIALIZE fails when the TPU$M_ 
COMMAND_DFLTED bit is set to 0 and no file 
is specified in the item list. 

TPU$M_CREATE 

CREATE 

DECTPU’s behavior is not affected by the this 
bit. Its interpretation is left to the application 
layered on DECTPU. 

TPU$M_DEBUG 

N/A 

If DECTPU senses the presence of the TPU$_ 
DEBUGFILE item, it tries to read the file, 
and then proceeds to compile and execute its 
contents as TPU statements. 

TPU$M_DEFAULTS 

N/A 

If DECTPU senses the presence of the TPU$_ 
DEFAULTSFILE item, it uses the specified 
DECwindows X resource file to initialize the 
DECwindows X resource database. 

TPU$M_DISPLAY 

DISPLAY 

If DECTPU senses the presence of the TPU$_ 
DISPLAYFILE item, it tries to image activate 
the specified image as its screen manager. When 
the bit is 0, DECTPU uses SYS$OUTPUT for 
display and only the READ_LINE built-in may 
be used for input. 

TPU$M_INIT 

INITIALIZATION 

If DECTPU senses the presence of the TPU$_ 
INIT_FILE item, it returns the specified string 
through the built-in GET_INFO (COMMAND, 
LINE, “INITIALIZATION_FILE”). Processing of 
the initialization file is left to the application. 

TPU$M_JOURNAL 

JOURNAL 

If DECTPU senses the presence of the TPU$_ 
JOURNALFILE item, it outputs the keystrokes 
entered during the editing session to the 
specified file. 

Note: Digital recommends the use of buffer 
change journaling in new applications. 

TPU$M_MODIFY 

MODIFY 

DECTPU’s behavior is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 

TPU$M_ 

NODEFAULTS 

N/A 

DECTPU initializes the DECwindows X resource 
database only with resource files that the 
DECwindows toolkit routine XtApplInitialize 
loads into the database. 


^The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field in which the bit is 
set. TPU$V_ is a bit number. 

^Most bits in the mask have a corresponding GET_INFO (COMMAND_LINE) request string. 


(continued on next page) 
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Table 6-3 (Cent.) Valid Masks for the TPU$K_OPTIONS Item Code 


Mask^ 

GETJNFO 

Request String^ 

Description 

TPU$M_NOMODIFY 

NOMODIFY 

DECTPU’s behavior is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 

TPU$M_OUTPUT 

OUTPUT 

DECTPU’s behavior is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 

TPU$M_READ 

READ.ONLY 

DECTPU’s behavior is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 

TPU$M_RECOVER 

RECOVER 

DECTPU’s behavior is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 

TPU$M_SECTION 

SECTION 

If DECTPU senses the presence of the TPU$_ 
SECTIONFILE item, it tries to read the 
specified file as a binary initialization file. 
TPU$INITIALIZE fails if this bit is set to 1 and 
the TPU$_SECTIONFILE item is not present in 
the item list. 

TPU$M_SEC_LNM_ 

MODE 

N/A 

If DECTPU senses the presence of the TPU$M_ 
SEC_LNM_MODE item, it looks only at 
executive mode logical names when attempting 
to read in a section file. 

TPU$M_WORK 

WORK 

If DECTPU senses the presence of the TPU$_ 
WORKFILE item, it uses the specifed file for 
memory management. If no item list entry is 
present, and this bit is set to 1, a file is created 
in SYS$LOGIN:.TPU$WORK. 

TPU$M_WRITE 

WRITE 

DECTPU’s behavior is not affected by this 
bit. Its interpretation is left to the application 
layered on DECTPU. 


^The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field in which the bit is 
set. TPU$V_ is a bit number. 

^Most bits in the mask have a corresponding GET_INFO (COMMAND_LINE) request string. 


To create the bits, start with the value 0, then use the OR operator on the mask 
(TPU$M . . . ) of each item you want to set. Another way to create the bits is to 
treat the 32 bits as a bit vector and set the bit (TPU$V . . . ) corresponding to the 
item you want. 
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user_arg 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

User argument. The user_arg argument is passed to the user-written 
initialization routine INITIALIZE. 

The user^arg parameter is provided to allow an application to pass information 
through TPU$INITIALIZE to the user-written initialization routine. DECTPU 
does not interpret this data in any way. 


Description 

This is the first routine that must be called after establishing a condition handler. 

This routine initializes the editor according to the information received from 
the callback routine. The initialization routine defaults all file specifications to 
the null string and all options to off. However, it does not default the file I/O or 
call-user routine addresses. 


Condition Values Returned 

TPU$_SUCCESS 

TPU$_SYSERROR 

TPU$_NONANSICRT 

TPU$_RESTOREFAIL 

TPU$_NOFILEROUTINE 

TPU$_INSVIRMEM 

TPU$_FAILURE 


Initialization was completed successfully. 

A system service did not work correctly. 

The input device (SYS$INPUT) is not a 
supported terminal. 

An error occurred during the restore operation. 

No routine has been established to perform file 
operations. 

Insufficient virtual memory exists for the editor 
to initialize. 

General code for all other errors during 
initialization. 
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TPU$MESSAGE—Write Message String 

The TPU$MESSAGE routine writes error messages and strings using the built-in 
procedure, MESSAGE. 

You can call this routine to have messages written and handled in a 
manner consistent with DECTPU. This routine should be used only after 
TPU$EXECUTE_INIFILE. 

Format 

TPU$MESSAGE string 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. 

_ Note _ 

The return status should be ignored because it is intended for use by the 
Put Message (SYS$PUTMSG) system service. 


Argument 

string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Formatted message. The string argument is the address of a descriptor of text 
to be written. It must be completely formatted. This routine does not append 
the message prefixes. However, the text is appended to the message buffer if one 
exists. In addition, if the buffer is mapped to a window, the window is updated. 
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TPU$PARSEINFO—Parse Command Line and Build Item List 

The TPU$PARSEINFO routine parses a command and builds the item list for 
TPU$INITIALIZE. 


Format 

TPU$PARSEINFO fileio ,calLuser 

Returns 

OpenVMS usage itemjist 
type longword (unsigned) 

access read only 

mechanism by reference 

The routine returns the address of an item list. 

Arguments 

fileio 

OpenVMS usage vector_longword_unsigned 
type bound procedure value 

access read only 

mechanism by descriptor 

File I/O routine. The fileio argument is the address of a descriptor of a file I/O 
routine. 

calLuser 

OpenVMS usage 
type 
access 
mechanism 

Call-user routine, 
call-user routine. 


vector_longword_unsigned 
bound procedure value 
read only 
by descriptor 

The call_user argument is the address of a descriptor of a 


Description 

The TPU$PARSEINFO routine parses a command and builds the item list for 
TPU$INITIALIZE. 

This routine uses the Command Language Interpreter (CLI) routines to parse 
the current command. It makes queries about the command parameters and 
qualifiers that DECTPU expects. The results of these queries are used to set up 
the proper information in an item list. The addresses of the user routines are 
used for those items in the list. The address of this list is the return value of the 
routine. 

If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls TPU$PARSEINFO interface. This is 
because TPU$PARSEINFO destroys all parse information obtained and stored 
before TPU$PARSEINFO was called. 
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TPU$SIGNAL—Signal a TPU Status 

This routine allows applications and user-written TPU routines such as FILEIO 
to easily signal error messages in order for TPU error handlers to perform 
correctly. 


Format 

TPU$SIGNAL condition-code 

Returns 

OpenVMS usage cond_value 

type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. In most cases, the routine returns either the same 
signal passed to it in the condition-value argument, or the return value of 
LIB$SIGNAL. If the routine fails, it signals TPU$_FAILURE and returns control 
to the caller. 

Arguments 

condition-code 

OpenVMS usage cond_value 

type longword (unsigned) 

access read only 

mechanism by value 

The condition-code is an unsigned longword that contains the condition code to be 
signaled. In most cases this argument is a TPU message code. 


Description 

TPU$SIGNAL performs a the same function as the Run-Time Library routine 
LIB$SIGNAL, but it also processes TPU facility messages to allow TPU language 
ON_ERROR handlers to be called. 

For example, assume a user-written file input/output routine is designed to signal 
the error TPU$_OPENIN when it fails to open a file. Calling the TPU$SIGNAL 
routine and passing the value TPU$_OPENIN allows a case-style TPU ON_ 
ERROR handler to receive the error, thus preserving the documented return 
values for TPU built-in procedures such as READ_FILE. 

_ Note _ 

You must call TPU$INITIALIZE before you call the TPU$SIGNAL 
routine. 
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If TPU$_QUITTING, TPU$_EXITING or TPU$_RECOVERFAIL are passed to 
the routine, it calls the RTL Library routine LIB$SIGNAL. 

If facility messages other than TPU messages are passed to the TPU$SIGNAL 
routine, it calls the LIB$SIGNAL routine and passes the appropriate condition- 
value. 
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TPU$SPECIFY_ASYNC_ACTION—Register an Asynchronous Action 

The TPU$SPECIFY_ASYNC_ACTION routine allows applications using the 
DECTPU full callable interface to register asynchronous actions with DECTPU. 

Format 

TPU$SPECIFY_ASYNC_ACTION facilityjndex [,tpu_statement] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

facilityjndex 

OpenVMS usage longword_unsigned 
type longword (signed) 

access read only 

mechanism by reference 

The facilityjndex argument represents an index of the asynchronous action. 
This index is used with the TPU$TRIGGER_ASYNC_ACTION routine to let 
DECTPU know what action to perform. It may also be used to delete an action 
routine (by omitting the tpu_statement). You may register several asynchronous 
actions depending on your application’s needs. This facility index number may be 
any positive integer. 

tpu_statement 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

This is the DECTPU statement you want executed when you call the 
TPU$TRIGGER_ASYNC_ACTION. The statement is compiled and then stored 
internally. If you omit the parameter, DECTPU removes the action from its list of 
asynchronous events. 

Description 

The TPU$SPECIFY_ASYNC_ACTION routine, along with TPU$TRIGGER_ 
ASYNC_ACTION, allow applications to interrupt DECTPU after calling 
TPU$CONTROL. The specified DECTPU statement is compiled and saved. 

This routine must be called after TPU$INITIALIZE. It will not complete 
successfully if keystroke journaling is enabled. 


DECTPU-66 






DEC Text Processing Utility (DECTPU) Routines 
TPU$SPECIFY_ASYNC_ACTION 


Condition Values Returned 

TPU$_SUCCESS 

TPU$_COMPILEFAIL 

TPU$_INVPARM 

TPU$_JNLACTIVE 


Normal successful completion. 

The code specified in tpu_statement did not 
compile successfully. 

An invalid parameter was passed. 

Keystroke journaling is active. This routine 
requires that either journaling be turned off, or 
that buffer change journaling be used. 
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TPU$TPU—Invoke DECTPU 


The TPU$TPU routine invokes DECTPU and is equivalent to the DCL command 
EDIT/TPU. 


Format 

TPU$TPU command 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Argument 


command 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Command string. Note that the verb is TPU instead of EDIT/TPU. The 
command argument is the address of a descriptor of a command line. 


Description 

This routine takes the command string specified and passes it to the editor. 
DECTPU uses the information from this command string for initialization 
purposes, just as though you had entered the command at the DCL level. 

Using the simplified callable interface does not set TPU$CLOSE_SECTION. This 
feature lets you make multiple calls to TPU$TPU without requiring you to open 
and close the section file on each call. 

If your application parses information that is not related to the operation of 
DECTPU, make sure the application obtains and uses all non-DECTPU parse 
information before the application calls TPU$TPU. This is because TPU$TPU 
destroys all parse information obtained and stored before TPU$TPU was called. 

Condition Values Returned 

This routine returns any condition value returned by TPU$INITIALIZE, 
TPU$EXECUTE_INFILE, TPU$CONTROL, and TPU$CLEANUP. 
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TPU$TRIGGER_ASYNC_ACTION—Execute DECTPU Command at 

Asynchronous Level 

The TPU$TRIGGER_ASYNC_ACTION routine allows applications using the 
DECTPU full callable interface to interrupt the DECTPU TPU$CONTROL loop 
at an asynchronous level. 


Format 

TPU$TRIGGER_ASYNC_ACTION facilityjndex 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

facilityjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

The facilityjndex argument represents the asynchronous action to be taken. 
This is the same index passed to the TPU$SPECIFY_ASYNC_ACTION routine 
registering what DECTPU statements to execute. 


Description 

The TPU$TRIGGER_ASYNC_ACTION routine, along with TPU$SPECIFY_ 
ASYNC_ACTION routine allow applications to interrupt DECTPU after calling 
TPU$CONTROL. The command that was specified for this facilityjndex is 
put on the DECTPU queue of work items and is handled as soon as no other 
work items are present. This allows DECTPU to complete and stabilize its 
environment before executing the command. This routine must be called after 
control has been passed to DECTPU via the TPU$CONTROL routine. 

Condition Values Returned 

TPU$_SUCCESS Normal successful completion. 

TPU$_UNKFACILITY The facilityjndex passed to this routine 

does not match any facility index passed to 
TPU$SPECIFY_ASYNC_ACTION. 
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FILEIO—User-Written Routine to Perform File Operations 

The user-written FILEIO routine is used to handle DECTPU file operations. The 
name of this routine can be either your own file I/O routine or the name of the 
DECTPU file I/O routine (TPU$FILEIO). 

Format 

FILEIO code ,stream ,data 

Returns 


OpenVMS usage cond_value 
type longword (usigned) 

access write only 

mechanism by reference 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

code 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Item code specifying a DECTPU function. The code argument is the address of 
a longword containing an item code from DECTPU, which specifies a function to 
perform. 

stream 

OpenVMS usage unspecified 
type longword (unsigned) 

access modify 

mechanism by reference 

File description. The stream argument is the address of a data structure 
containing four longwords. This data structure is used to describe the file to be 
manipulated. 

data 

OpenVMS usage item_list_3 
type longword (unsigned) 

access modify 

mechanism by reference 

Stream data. The data argument is either the address of an item list or the 
address of a descriptor. 


_ Note _ 

The value of this parameter depends on which item code you specify. 
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Description 

The bound procedure value of this routine is specified in the item list built by 
the callback routine. This routine is called to perform file operations. Instead 
of using your own file I/O routine, you can call TPU$FILEIO and pass it the 
parameters for any file operation that you do not want to handle. Note, however, 
that TPU$FILEIO must handle all I/O requests for any file it opens. Also, if it 
does not open the file, it cannot handle any I/O requests for the file. In other 
words, you cannot intermix the file operations between your own file I/O routine 
and the one supplied by DECTPU. 

Condition Values Returned 

The Condition Values Returned are determined by the user and should indicate 
success or failure of the operation. 
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FILE_PARSE—User-Written Routine to Perform File Parse 
Operations 

This is a user-written routine that can be used in place of the TPU$FILE_PARSE 
routine. 

Format 

FILE_PARSE result-string, flags, filespec, default-spec, related-spec 

Returns 

OpenVMS usage cond_value 

type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. The return value is ignored by DECTPU. User-written 

FILE_PARSE routines should include calls to the TPU$SIGNAL routine to ensure 
proper error handling. 

Arguments 

result-string 

OpenVMS usage char_string 

type character string 

access write only 

mechanism by descriptor 

Return value for the built-in procedure FILE_PARSE. The calling program should 
fill in this descriptor with a dynamic string allocated by the string routines, such 
as the RTL routine LIB$SGET1_DD. DECTPU frees this string when necessary. 

flags 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Table 6-4 lists the valid flag values used to request file specification components. 

Table 6-4 Values for FILE_PARSE Flags Argument 


Flag Bit^ 

Description 

TPU$M_NODE 

TPU$M_DEV 

TPU$M_DIR 

TPU$M_NAME 

TPU$M_TYPE 

Request for the node component of the filespec. 
Request for the device component of the filespec. 
Request for the directory component of the filespec. 
Request for the name component of the filespec. 
Request for the type component of the filespec. 


^TPU$M . . . indicates a mask. There is a corresponding value for each mask in the form TPU$V . . . . 


(continued on next page) 
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Table 6-4 (Cent.) Values for FILE_PARSE Flags Argument 


Flag Bit^ 

Description 

TPU$M_VER 

Request for the version component of the filespec. 

TPU$M_HEAD 

Request for the NODE, DEVICE, and 
DIRECTORY components of the filespec. 

TPU$M_TAIL 

Request for NAME, TYPE, and VERSION 
components of the filespec. 

^TPU$M . . . indicates a mask. There is a corresponding value for each mask in the form TPU$V . . . . 

filespec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 

The object file specification. 

default-spec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 

Contains the default file specification. The value 0 is passed if there is no 
default-spec. 

related-spec 

OpenVMS usage 

char_string 

type 

character string 

access 

read only 

mechanism 

by descriptor 


The related-spec contains the related file specification. The value 0 is passed if 
there is no related-spec. 


Description 

This routine allows an application to replace the TPU$FILE_PARSE routine with 
its own file parsing routine. The calling program passes the address of the file 
parsing routine to TPU$INITIALIZE using the TPU$_FILE_PARSE item code. 

When the DECTPU built-in procedure FILE_PARSE is called from TPU code, 
DECTPU calls either the user-written file_parse routine (if one was passed to 
TPU$INITIALIZE) or the TPU$FILE_PARSE routine. The return value of the 
built-in procedure is the string returned in the result-string argument. 

To ensure proper operation of the user’s ON_ERROR error handlers, errors should 
be signaled using the TPU$SIGNAL routine. 
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FILE_SEARCH—User-Written Routine to Perform File Search 

Operations 

This is a user-written routine that is used in place of the TPU$FILE_SEARCH 
routine. 

Format 

FILE_SEARCH result-string, flags, filespec, default-spec, related-spec 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. If an odd numeric value is returned, the next call to 
the built-in procedure FILE_SEARCH automatically sets the TPU$M_REPARSE 
bit in the flags longword. TPU$M_REPARSE is also set if the result-string has a 
length of 0. 

Arguments 

result-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Return value for the built-in procedure FILE_SEARCH. Your program should fill 
in this descriptor with a dynamic string allocated by the string routines such as 
the RTL LIB$SGET1_DD routine. DECTPU frees this string when necessary. 

The TPU$M_REPARSE bit is set in the flags longword if the result-string has a 
length of zero. The bit is intended to reset the file search when wildcard searches 
are performed. 

flags 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Table 6-5 shows the flags used for specifying the file components. 

Table 6-5 Values for FILE_SEARCH Flags Argument 


Flag Bit^ 

Description 

TPU$M_NODE 

TPU$M_DEV 

Request for the node component of the filespec. 
Request for the device component of the filespec. 


^TPU$M . . . indicates a mask. There is a corresponding value for each mask in the form TPU$V . . . . 


(continued on next page) 
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Table 6-5 (Cent.) Values for FILE_SEARCH Flags Argument 

Flag Bit^ Description 


TPU$M_DIR 

TPU$M_NAME 

TPU$M_TYPE 

TPU$M_VER 

TPU$M_REPARSE 


TPU$M_HEAD 

TPU$M_TAIL 


Request for the directory component of the filespec. 
Request for the name component of the filespec. 
Request for the type component of the filespec. 
Request for the version component of the filespec. 

Reparse the filespec before processing. This is 
intended as a way to restart the file search. This 
flag will automatically be set by DECTPU if on a 
previous call to the FILE_SEARCH user routine 
the result-string has a zero length or the routine 
returns a odd (noneven) status. 

Request for the NODE, DEVICE, and 
DIRECTORY components of the filespec. 

Request for NAME, TYPE, and VERSION 
component of the filespec. 


^TPU$M . . . indicates a mask. There is a corresponding value for each mask in the form TPU$V . . . . 


filespec 

OpenVMS usage char_string 

type character string 

access read only 

mechanism by descriptor 

The object file specification. 

default-spec 

OpenVMS usage char_string 

type character string 

access read only 

mechanism by descriptor 

The default-spec contains the default file specification. 
The value 0 is passed if there is no default-spec. 

related-spec 

OpenVMS usage char_string 

type character string 

access read only 

mechanism by descriptor 

The related-spec contains the related file specification. 
The value 0 is passed if there is no related-spec. 
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Description 

The FILE_SEARCH user routine allows an application to replace the TPU$FILE_ 
SEARCH routine with its own file-searching routine. The calling program passes 
the address of the routine to the TPU$INITIALIZE routine using the TPU$_ 
FILE_SEARCH item code. 

When the DECTPU built-in procedure FILE_SEARCH is called from TPU code, 
DECTPU calls either the user-written FILE_SEARCH routine (if one was passed 
to TPU$INITIALIZE) or the TPU$FILE_SEARCH routine. The return value of 
the built-in procedure is the string returned in the result-string argument. 

To ensure proper operation of the user’s ON_ERROR handlers, errors in the user 
written FILE_PARSE routine should be signaled using the TPU$SIGNAL routine. 
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HANDLER—User-Written Condition Handling Routine 

The user-written HANDLER routine performs condition handling. 


Format 

HANDLER signaLvector ,mechanism_vector 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. 

Arguments 

signaLvector 

OpenVMS usage arg_list 
type longword (unsigned) 

access modify 

mechanism by reference 

Signal vector. See the OpenVMS System Services Reference Manual for 
information about the signal vector passed to a condition handler. 

mechanism_vector 

OpenVMS usage arg_list 
type longword (unsigned) 

access read only 

mechanism by reference 

Mechanism vector. See the OpenVMS System Services Reference Manual for 
information about the mechanism vector passed to a condition handler. 


Description 

If you need more information about writing condition handlers and programming 
concepts, refer to OpenVMS Programming Interfaces: Calling a System Routine. 

Instead of writing your own condition handler, you can use the default condition 
handler, TPU$HANDLER. If you want to write your own routine, you must call 
TPU$HANDLER with the same parameters that your routine received to handle 
DECTPU internal signals. 
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INITIALIZE—User-Written Initialization Routine 

The user-written initialization callback routine is passed to TPU$INITIALIZE 
as a bound procedure value and called to supply information needed to initialize 
DECTPU. 

Format 

INITIALIZE [user_arg] 

Returns 

VMS Usage: item_list 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

This routine returns the address of an item list. 

Arguments 

user_arg 

OpenVMS usage 
type 
access 
mechanism 

User argument. 

Description 

The user-written initialization call-back routine is passed to TPU$INITIALIZE 
as a bound procedure value and called to supply information needed to initialize 
DECTPU. 

If the user_arg parameter was specified in the call to TPU$INITIALIZE, the 
initialization call-back routine is called with only that parameter. If user_arg 
was not specified in the call to TPU$INITIALIZE, the initialization call-back 
routine is called with no parameters. 

The user_arg parameter is provided to allow an application to pass information 
through TPU$INITIALIZE to the user-written initialization routine. DECTPU 
does not interpret this data in any way. 

The user-written call-back routine is expected to return the address of an item 
list containing initialization parameters. Because the item list is used outside 
the scope of the initialization call-back routine, it should be allocated in static 
memory. 

The item list entries are discussed in the section on TPU$INITIALIZE. Most of 
the initialization parameters have a default value; strings default to the null 
string, and flags default to false. The only required initialization parameter is the 
address of a routine for file I/O. If an entry for the file I/O routine address is not 
present in the item list, TPU$INITIALIZE returns with a failure status. 


user_arg 

longword (unsigned) 
read only 
by value 
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USER—User-Written Routine Called from a DECTPU Editing Session 

The user-written USER routine allows your program to get control during a 
DECTPU editing session (for example, to leave the editor temporarily and 
perform a calculation). 


Format 


USER integer ,stringin ,stringout 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. 


Arguments 

integer 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

First parameter to the built-in procedure CALL_USER. This is an input-only 
parameter and must not be modified. 

stringin 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Second parameter to the built-in procedure CALL_USER. This is an input-only 
parameter and must not be modified. 

stringout 

OpenVMS usage char_string 
type character string 

access modify 

mechanism by descriptor 

Return value for the built-in procedure CALL_USER. Your program should fill 
in this descriptor with a dynamic string allocated by the string routines (such as 
lib$sgetl_dd) provided by the OpenVMS Run-Time Library. The DECTPU editor 
frees this string when necessary. 
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Description 

This user-written routine is invoked by the DECTPU built-in procedure CALL_ 
USER. The built-in procedure CALL_USER passes three parameters to this 
routine. These parameters are then passed to the appropriate part of your 
application to be used as specified. (For example, they can be used as operands in 
a calculation within a FORTRAN program.) Using the string routines provided 
by the OpenVMS Run-Time Library, your application fills in the stringout 
parameter in the call-user routine, which returns the stringout value to the 
built-in procedure CALL_USER. 

The description of the built-in procedure CALL_USER in the DEC Text Processing 
Utility Reference Manual shows an example of a BASIC program that is a 
call-user routine. 

See Section 6.5 for a description of how to create an executeable image for the 
USER routine and how to call the routine from a C program in the DECTPU 
environment. 
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On OpenVMS operating systems, the EDT editor can be called from a program 
written in any language that generates calls using the OpenVMS Calling 
Standard. 

You can set up your call to EDT so that the program handles all the editing 
work, or you can make EDT run interactively so that you can edit a file while the 
program is running. 

This chapter on callable EDT assumes that you know how to call an external 
facility from the language you are using. Callable EDT is a shareable image, 
which means that you save physical memory and disk space by having all 
processes access a single copy. 

7.1 Introduction to EDT Routines 

You must include a statement in your program accessing the EDT entry point. 
This reference statement is similar to a library procedure reference statement. 
The EDT entry point is referenced as EDT$EDIT. You can pass arguments 
to EDT$EDIT; for example, you can pass EDT$FILEIO or your own routine. 
When you refer to the routines you pass, call them FILEIO, WORKIO, and 
XLATE. Therefore, FILEIO can be either a routine provided by EDT (named 
EDT$FILEIO) or a routine that you write. 

7.2 Using EDT Routines: An Example 

Example 7—1 shows a VAX BASIC program that calls EDT. All three routines 
(FILEIO, WORKIO, and XLATE) are called. Note the reference to the entry point 
EDT$EDIT in line number 500. 


Example 7-1 Using the EDT Routines in a VAX BASIC Program 


100 EXTERNAL INTEGER EDT$FILEIO O 
200 EXTERNAL INTEGER EDT$W0RKI0 
250 EXTERNAL INTEGER AXLATE 
300 EXTERNAL INTEGER FUNCTION EDT$EDIT 
400 DECLARE INTEGER RESULT 

450 DIM INTEGER PASSFILE(1%) © 

460 DIM INTEGER PASSW0RK(1%) 

465 DIM INTEGER PASSXLATE(1%) 

470 PASSFILE(0%) = LOC(EDT$FILEIO) 

480 PASSWORK(0%) = L0C(EDT$W0RKI0) 

485 PASSXLATE(0%) = LOC(AXLATE) 


(continued on next page) 
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7.2 Using EDT Routines: An Example 


Example 7-1 (Cent.) Using the EDT Routines in a VAX BASiC Program 

500 RESULT = EDT$EDIT('FILE.BAS''EDTINI',0%, 0 

PASSFILE(0%)BY REF, PASSWORK(0%) BY REF, O 
PASSXLATE(0%) BY REF) 0 

600 IF (RESULT AND 1%) = 0% 

THEN 

PRINT "SOMETHING WRONG" 

CALL LIB$STOP(RESULT BY VALUE) 

900 PRINT "EVERYTHING O.K." 

1000 END 

O The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE are 
defined so that they can be passed to callable EDT. 

0 Arrays are used to construct the two-longword structure needed for data type 
BPV. 

0 Here is the call to EDT. The input file is FILE.BAS, the output and journal 
files are defaulted, and the command file is EDTINI. A 0 is passed for the 
options word to get the default EDT options. 

O The array PASSFILE points to the entry point for all file I/O, which is set 
up in this example to be the EDT-supplied routine with the entry point 
EDT$FILEIO. Similarly, the array PASSWORK points to the entry point 
for all work I/O, which is the EDT-supplied routine with the entry point 
EDT$WORKIO. 

© PASSXLATE points to the entry point that EDT will use for all XLATE 
processing. PASSXLATE points to a user-supplied routine with the entry 
point AXLATE. 


7.3 EDT Routines 

The following pages describe the individual EDT routines. 
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EDT$EDIT—Edit a File 


The EDT$EDIT routine invokes the EDT editor. 


Format 

EDT$EDIT in_file [,out_file] [,com_file] [,jou_file] [.options] [.fileio] [.workioj [,xlate] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

in_file 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

File specification of the input file that EDT$EDIT is to edit. The in_file argument 
is the address of a descriptor pointing to this file specification. The string that 
you enter in this calling sequence is passed to the FILEIO routine to open the 
primary input file. This is the only required argument. 

out_file 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

File specification of the output file that EDT$EDIT creates. The out_file 
argument is the address of a descriptor pointing to this file specification. The 
default is that the input file specification is passed to the FILEIO routine to open 
the output file for the EXIT command. 

com_file 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

File specification of the startup command file to be executed when EDT is 
invoked. The com__file argument is the address of a descriptor pointing to this 
file specification. The com__file string is passed to the FILEIO routine to open 
the command file. The default is the same as that for EDT command file defaults. 
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jou_file 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

File specification of the journal file to be opened when EDT is invoked. The 
jou_file argument is the address of a descriptor pointing to this file specification. 
The jou_file string is passed to the FILEIO routine to open the journal file. The 
default is to use the same file name as in__file. 

options 

OpenVMS usage maskjongword 
type aligned bit string 

access read only 

mechanism by reference 

Bit vector specifying options for the edit operation. The options argument is the 
address of an aligned bit string containing this bit vector. Only bits <5:0> are 
currently defined; all others must be 0. The default options have all bits set to 0. 
This is the same as the default setting when you invoke EDT to edit a file from 
DCL. 

Symbols and their descriptions follow: 

EDT$M_RECOVER If set, bit <0> causes EDT to read the journal file 

and execute the commands in it, except for the 
EXIT or QUIT commands, which are ignored. After 
the journal file commands are processed, editing 
continues normally. If bit <0> is set, the FILEIO 
routine is asked to open the journal file for both input 
and output; otherwise FILEIO is asked only to open 
the journal file for output. Bit <0> corresponds to the 
/RECOVER qualifier on the EDT command line. 

EDT$M_COMMAND If set, bit <1> causes EDT to signal if the startup 

command file cannot be opened. When bit <1> 
is 0, EDT intercepts the signal from the FILEIO 
routine indicating that the startup command file 
could not be opened. Then, EDT proceeds with 
the editing session without reading any startup 
command file. If no command file name is supplied 
with the call to the EDT$EDIT routine, EDT tries 
to open SYS$LIBRARY:EDTSYS.EDT or, if that 
fails, EDTINI.EDT. Bit <1> corresponds to the 
/COMMAND qualifier on the EDT command line. If 
EDT$M_NOCOMMAND (bit <4>) is set, bit <1> is 
overridden because bit <4> prevents EDT from trying 
to open a command file. 

EDT$M_NOJOURNAL If set, bit <2> prevents EDT from opening the journal 

file. Bit <2> corresponds to the /NOJOURNAL or 
/READ_ONLY qualifier on the EDT command line. 
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EDT$M_NOOUTPUT 


EDT$M_NOCOMMAND 

EDT$M_NOCREATE 


If set, bit <3> prevents EDT from using the input 
file name as the default output file name. Bit <3> 
corresponds to the /NOOUTPUT or /READ_ONLY 
qualifier on the EDT command line. 

If set, bit <4> prevents EDT from opening a 
startup command file. Bit <4> corresponds to the 
/NOCOMMAND qualifier on the EDT command line. 

If set, bit <5> causes EDT to return to the caller if 
the input file is not found. The status returned is the 
error code EDT$_INPFILNEX. 


fileio 

OpenVMS usage vector_longword_unsigned 
type bound procedure value 

access function call 

mechanism by reference 

User-supplied routine called by EDT to perform file I/O functions. The fileio 
argument is the address of a bound procedure value containing the user-supplied 
routine. When you do not need to intercept any file I/O, either use the entry point 
EDT$FILEIO for this argument or omit it. When you only need to intercept some 
amount of file I/O, call the EDT$FILEIO routine for the other cases. 

To avoid confusion, note that EDT$FILEIO is a routine provided by EDT whereas 
FILEIO is a routine that you provide. 

In order to accommodate routines written in high-level languages that do up-level 
addressing, this argument must have a data type of BPV (bound procedure value). 
BPV is a two-longword entity in which the first longword contains the address 
of a procedure value and the second longword is the environment value. When 
the bound procedure is called, EDT loads the second longword into Rl. If you use 
EDT$FILEIO for this argument, set the second longword to <0>. You can pass a 
<0> for the argument, and EDT will set up EDT$FILEIO as the default and set 
the environment word to 0, 

workio 

OpenVMS usage vector_longword_unsigned 
type bound procedure value 

access function call 

mechanism by reference 

User-supplied routine called by EDT to perform I/O between the work file and 
EDT. The workio argument is the address of a bound procedure value containing 
the user-supplied routine. Work file records are addressed only by number and 
are always 512 bytes long. If you do not need to intercept work file I/O, you can 
either use the entry point EDT$WORKIO for this argument or omit it. 

In order to accommodate routines written in high-level languages that do up-level 
addressing, this argument must have a data type of BPV (bound procedure value). 
This means that EDT loads Rl with the second longword addressed before calling 
it. If EDT$WORKJO is used for this argument, set the second longword to 0. 

You can pass a 0 for this argument, and EDT will set up EDT$WORKIO as the 
default and set the environment word to 0. 


EDT-5 



EDT Routines 
EDT$EDIT 

xiate 

OpenVMS usage vector_longword_unsigned 
type bound procedure value 

access function call 

mechanism by reference 

User-supplied routine that EDT calls when it encounters the nokeypad command 
XLATE. The xiate argument is the address of a bound procedure value containing 
the user-supplied routine. The XLATE routine allows you to gain control of your 
EDT session. If you do not need control of EDT during the editing session, you 
can either use the entry point EDT$XLATE for this argument or omit it. 

In order to accommodate routines written in high-level languages that do up-level 
addressing, this argument must have a data type of BPV (bound procedure value). 
This means that EDT loads R1 with the second longword addressed before calling 
it. If EDT$XLATE is used for this argument, set the second longword to 0. You 
can pass a 0 for this argument, and EDT will set up EDT$XLATE as the default 
and set the environment word to 0. 

Description 

If the EDT session is terminated by EXIT or QUIT, the status will be a successful 
value (bit <0> = 1). If the session is terminated because the file was not 
found and if the /NOCREATE qualifier was in effect, the failure code EDT$_ 
INPFILNEX is returned. In an unsuccessful termination caused by an EDT error, 
a failure code corresponding to that error is returned. Each error status from the 
FILEIO and WORKIO routines is explained separately. 

Three of the arguments to the EDT$EDIT routine, fileio, workio, and xiate are 
the entry point names of user-supplied routines. 

Condition Values Returned 

SS$_NORMAL Successful completion. 

EDT$_INPFILNEX /NOCREATE specified and input file does not 

exist. 

This routine also returns any condition values returned by user-supplied routines. 
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FILEIO 

The user-supplied FILEIO routine performs file I/O functions. You call it by 
specifying it as an argument in the EDT$EDIT routine. It cannot be called 
independently. 

Format 

FILEIO code ,stream ,record ,rhb 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

A status code that your FILEIO routine returns to EDT$EDIT. The fileio 
argument is a longword containing the status code. The only failure code that 
is normally returned is RMS$_EOF from a GET call. All other RMS errors are 
signaled, not returned. The RMS signal should include the file name and both 
longwords of the RMS status. Any errors detected with the FILEIO routine can 
be indicated by setting status to an error code. That special error code will be 
returned to the program by the EDT$EDIT routine. There is a special status 
value EDT$_NONSTDFIL for nonstandard file opening. 

Condition values are returned in RO. 


Arguments 

code 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

A code from EDT that specifies what function the FILEIO routine is to perform. 
The code argument is the address of a longword integer containing this code. 
Following are the valid function codes: 


Function Code 

EDT$K_OPEN_INPUT 

EDT$K_OPEN_OUTPUT_SEQ 

EDT$K_OPEN_OUTPUT_NOSEQ 


Description 

The record argument names a file to be 
opened for input. The rhb argument is 
the default file name. 

The record argument names a file to 
be opened for output as a sequenced file. 
The rhb argument is the default file 
name. 

The record argument names a file to be 
opened for output. The rhb argument is 
the default file name. 
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Function Code 

Description 

EDT$K_OPEN_IN_OUT 

The record argument names a file to be 
opened for both input and output. The 
rhb argument is the default file name. 

EDT$K_GET 

The record argument is to be filled with 
data from the next record of the file. If 
the file has record prefixes, rhb is filled 
with the record prefix. If the file has no 
record prefixes, rhb is not written. When 
you attempt to read past the end of file, 
status is set to RMS$_EOF. 

EDT$K_PUT 

The data in the record argument is to 
be written to the file as its next record. 

If the file has record prefixes, the record 
prefix is taken from the rhb argument. 
For a file opened for both input and 
output, EDT$K_PUT is valid only at the 
end of the file, indicating that the record 
is to be appended to the file. 

EDT$K_CLOSE_DEL 

The file is to be closed and then deleted. 
The record and rhb arguments are not 
used in the call. 

EDT$K_CLOSE 

The file is to be closed. The record and 
rhb arguments are not used in the call. 


Stream 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

A code from EDT that indicates which file is being used. The stream argument 
is the address of a longword integer containing the code. Following are the valid 
codes. 


Function Code 


Description 


EDT$K_COMMAND_FILE 

EDT$K_INPUT_FILE 

EDT$K_INCLUDE_FILE 


The command file. 

The primary input file. 

The secondary input file. Such a file is opened 
in response to an INCLUDE command. It is 
closed when the INCLUDE command is complete 
and will be reused for subsequent INCLUDE 
commands. 
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Function Code 

Description 

EDT$K_JOURNAL_FILE 

The journal file. If bit 0 of the options is set, it 
is opened for both input and output and is read 
completely. Otherwise, it is opened for output 
only. After it is read or opened for output only, it 
is used for writing. On a successful termination 
of the editing session, the journal file is closed 
and deleted. EXIT/SAVE and QUIT/SAVE close 
the journal file without deleting it. 

EDT$K_OUTPUT_FILE 

The primary output file. It is not opened until 
you enter the EXIT command. 

EDT$K_WRITE_FILE 

The secondary output file. Such a file is opened 
in response to a WRITE or PRINT command. 

It is closed when the command is complete and 
will be reused for subsequent WRITE or PRINT 
commands. 


record 

OpenVMS usage char_string 
type character-coded text string 

access modify 

mechanism by descriptor 

Text record passed by descriptor from EDT to the user-supplied FILEIO routine; 
the code argument determines how the record argument is used. The record 
argument is the address of a descriptor pointing to this argument. When the 
code argument starts with EDT$K_OPEN, the record is a file name. When the 
code argument is EDT$K_GET, the record is a place to store the record that 
was read from the file. For code argument EDT$K_PUT, the record is a place 
to find the record to be written to the file. This argument is not used if the code 
argument starts with EDT$K_CLOSE. 

Note that for EDT$K_GET, EDT uses a dynamic or varying string descriptor; 
otherwise, EDT has no way of knowing the length of the record being read. EDT 
uses only string descriptors that can be handled by the Run-Time Library (RTL) 
routine STR$COPY_DX. 

rhb 

OpenVMS usage char_string 
type character-coded text string 

access modify 

mechanism by descriptor 

Text record passed by descriptor from EDT to the user-supplied FILEIO routine; 
the code argument determines how the rhb argument is used. When the code 
argument starts with EDT$K_OPEN, the rhb argument is the default file name. 
When the code is EDT$K_GET and the file has record prefixes, the prefixes are 
put in this argument. When the code is EDT$K_PUT and the file has record 
prefixes, the prefixes are taken from this argument. Like the record argument, 
EDT uses a dynamic or varying string descriptor for EDT$K_GET and uses only 
string descriptors that can be handled by the RTL routine STR$COPY_DX. 
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Description 

If you do not need to intercept any file I/O, you can use the entry point 
EDT$FILEIO for this argument or you can omit it. If you need to intercept 
only some file I/O, call the EDT$FILEIO routine for the other cases. 

When you use EDT$FILEIO as a value for the fileio argument, files are opened 
as follows: 

• The record argument is always the RMS file name. 

• The rhb argument is always the RMS default file name. 

• There is no related name for the input file. 

• The related name for the output file is the input file with OFF (output file 
parse). EDT passes the input file name, the output file name, or the name 
from the EXIT command in the record argument. 

• The related name for the journal file is the input file name with the output 
file parse (OFF) RMS bit set. 

• The related name for the INCLUDE file is the input file name with the OFF 
set. This is unusual because the file is being opened for input. 

Condition Values Returned 

SS$_NORMAL Successful completion. 

EDT$_NONSTDFIL File is not in standard text format. 

RMS$_EOF End of file on a GET. 
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WORKIO 

The user-supplied WORKIO routine is called by EDT when it needs temporary 
storage for the file being edited. You call it by specifying it as an argument in the 
EDT$EDIT routine. It cannot be called independently. 

Format 

WORKIO code ,recordno ,record 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by immediate value 

Longword value returned as a status code. It is generally a success code, because 
all OpenVMS RMS errors should be signaled. The signal should include the file 
name and both longwords of the OpenVMS RMS status. Any errors detected 
within work I/O can be indicated by setting status to an error code, which will be 
returned by the EDT$EDIT routine. 

The condition value is returned in RO. 

Arguments 

code 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

A code from EDT that specifies the operation to be performed. The code 
argument is the address of a longword integer containing this argument. The 
valid function codes are as follows: 


Function Code 

Description 

EDT$K_OPEN_IN_OUT 

Open the work file for both input and output. 
Neither the record nor recordno argument is 
used. 

EDT$K_GET 

Read a record. The recordno argument is the 
number of the record to be read. The record 
argument gives the location where the record is to 
be stored. 

EDT$K_PUT 

Write a record. The recordno argument is the 
number of the record to be written. The record 
argument tells the location of the record to be 
written. 

EDT$K_CLOSE_DEL 

Close the work file. After a successful close, the 
file is deleted. Neither the record nor recordno 
argument is used. 
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recordno 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Number of the record to be read or written. The recordno argument is the 
address of a longword integer containing this argument. EDT always writes a 
record before reading that record. This argument is not used for open or close 
calls. 

record 

OpenVMS usage char_string 
type character string 

access modify 

mechanism by descriptor 

Location of the record to be read or written. This argument always refers to a 
512-byte string during GET and PUT calls. This argument is not used for open 
or close calls. 

Description 

Work file records are addressed only by number and are always 512 bytes 
long. If you do not need to intercept work file I/O, you can use the entry point 
EDT$WORKIO for this argument or you can omit it. 

Condition Value Returned 

SS$_NORMAL Successful completion. 
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XLATE 


The user-supplied XLATE routine is called by EDT when it encounters the 
nokeypad command XLATE. You cause it to be called by specifying it as an 
argument in the EDT$EDIT routine. It cannot be called independently. 


Format 


Returns 


XLATE string 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword value returned as a status code. It is generally a success code. If the 
XLATE routine cannot process the passed string for some reason, it sets status 
to an error code. Returning an error code from the XLATE routine aborts the 
current key execution and displays the appropriate error message. 


The condition value is returned in RO. 


Argument 

string 

OpenVMS usage char_string 
type character-coded text string 

access modify 

mechanism by descriptor 

Text string passed to the nokeypad command XLATE. You can use the nokeypad 
command XLATE by defining a key to include the following command in its 
definition: 

XLATEtext'Z 

The text is passed by the string argument. The string argument is one that can 
be handled by the Run-Time Library (RTL) routine STR$COPY_DX. 

This argument is also a text string returned to EDT. The string is made up of 
nokeypad commands that EDT is to execute. 


Description 

The nokeypad command XLATE allows you to gain control of the EDT session. 
(See the OpenVMS EDT Reference Manual for more information about the XLATE 
command.) If you do not need to gain control of EDT during the editing session, 
you can use the entry point EDT$XLATE for this argument or you can omit it. 

Condition Value Returned 

SS$_NORMAL Successful completion. 
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This chapter describes the File Definition Language (FDL) routines. These 
routines perform many of the functions of the File Definition Language that 
define file characteristics. Typically, you use FDL to perform the following 
operations: 

• Specify file characteristics otherwise unavailable from your language. 

• Examine or modify the file characteristics of an existing data file in order to 
improve program or system interaction with that file. 


8.1 Introduction to FDL Routines 

You specify FDL attributes for a data file when you use FDL to create the data 
file, set the desired file characteristics, and close the file. You can then use the 
appropriate language statement to reopen the file. Because the data file is closed 
between the time the FDL attributes are set and the time your program accesses 
the file, you cannot use FDL to specify run-time attributes (attributes that are 
ignored or deleted when the associated data file is closed). 

The FDL$CREATE routine is the one most likely to be called from a high- 
level language. It creates a file from an FDL specification and then closes the 
file. The following DEC Fortran program segment creates an empty data file 
named INCOME93.DAT using the file characteristics specified by the FDL file 
INCOME.FDL. The STATEMENT variable contains the number of the last FDL 
statement processed by FDL$CREATE; this argument is useful for debugging an 
FDL file. 

INTEGER STATEMENT 
INTEGER STATUS, 

2 FDL$CREATE 

STATUS = FDL$CREATE ('INCOME.FDL', 

2 'INCOME93.DAT', 

2 ,, ! I 

2 STATEMENT, 

2 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL(STATUS)) 


The following three FDL routines provide a way to specify all the options RMS 
allows when it executes create, open, or connect operations. They also allow you 
to specify special processing options required for your applications. 

• The FDL$GENERATE routine produces an FDL specification by interpreting 
a set of RMS control blocks in an existing data file. It then writes the 
FDL specification either to an FDL file or to a character string. If 
your programming language does not provide language statements that 
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access RMS control blocks (for example, DEC Fortran), you must use 
FDL$GENERATE from within the context of a user-open routine to generate 
an FDL file. 

• The FDL$PARSE routine parses an FDL specification, allocates RMS control 
blocks, and fills in the relevant fields. 

• The FDL$RELEASE routine deallocates the virtual memory used by the RMS 
control blocks created by FDL$PARSE. 

These routines cannot be called from AST level. 

An FDL specification can be in either a file or a character string. When specifying 

an FDL specification in a character string, delimit the statements of the FDL 

specification with semicolons. 

8.2 Using the FDL Routines: Examples 

This section provides examples that demonstrate the use of the FDL routines in 

various programming scenarios, including the following: 

• Example 8—1 shows how to use the FDL$CREATE routine in a FORTRAN 
program. 

• Example 8—2 shows how to use the FDL$PARSE and FDL$RELEASE 
routines in a C program. 

• Example 8—3 shows a DEC Pascal program that uses the FDL$PARSE 
routine to fill in the RMS control blocks in a data file. The program then uses 
the FDL$GENERATE routine to create an FDL file using the information in 
the control blocks. 
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Example 8-1 Using FDL$CREATE in a FORTRAN Program 

* This program calls the FDL$CREATE routine. It 

* creates an indexed output file named NEW_MASTER.DAT 

* from the specifications in the FDL file named 

* INDEXED.FDL. You can also supply a default filename 

* and a result name (that receives the name of the 

* created file). The program also returns all the 

* statistics. 

* 

IMPLICIT INTEGER*4 (A - Z) 

EXTERNAL LIB$GET_LUN, FDL$CREATE 

CHARACTER IN_FILE*11 /'INDEXED.FDL'/, 

1 OUT_FILE * 14 /'NEW_MASTER.DAT'/, 

1 DEF_FILE*11 /'DEFAULT.FDL'/, 

1 RES_FILE*50 

INTEGER*4 FIDBLK(3) 70,0,0/ 

1 = 1 

STATUS = FDL$CREATE (IN_FILE,OUT_FILE, 
DEF_FILE,RES_FILE,FIDBLK,,) 

IF (.NOT. STATUS) CALL LIB$STOP (%VAL(STATUS)) 

STATUS=LIB$GET_LUN(LOG_UNIT) 

OPEN {UNIT=LOG_UNIT,FILE=RES_FILE,STATUS='OLD') 

CLOSE (UNIT=LOG_UNIT, STATUS='KEEP') 

WRITE (6,1000) (RES_FILE) 

WRITE (6,2000) (FIDBLK (I), 1=1,3) 

1000 FORMAT (IX,'The result filename is: ',A50) 

2000 FORMAT (/IX,'FID-NUM: ',15/, 

1 1X,'FID-SEQ: ',15/, 

1 1X,'FID-RVN: ',15) 

END 


Example 8-2 Using FDL$PARSE and FDL$RELEASE in a C Program 

/* FDLEXAM.C 

** This program calls the FDL utility routines FDL$PARSE and 
** FDL$RELEASE. First, FDL$PARSE parses the FDL specification 
** PART.FDL. Then the data file named in PART.FDL is accessed 
** using the primary key. Last, the control blocks allocated 
** by FDL$PARSE are released by FDL$RELEASE. 

** Note; to try this program use the following command on any 
** file with textual data: $ANALYZE/RMS/FDL/OUT=PART.FDL 
*/ 

tinclude <descrip> 

#include <rms> 

idefine REC_SIZE 80 /* as appropriate for files used */ 

FDLEXAM () 

{ 

Struct FAB *fab_ptr; /* variable to hold pointer to FAB structure */ 
struct RAB *rab_ptr; /* variable to hold pointer to RAB structure */ 
$DESCRIPTOR (fdl_file, "PART.FDL"); /* free choice of name */ 

char record_buffer[REC_SIZE+l]; /* allow for null terminator */ 

int stat; 


(continued on next page) 
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Example 8-2 (Cent.) Using FDL$PARSE and FDL$RELEASE in a C Program 

/* 

** Read and parse FDL file allocating and initializing RAB and 
** and FAB accordingly, returning pointers to the FAB & RAB. 

*/ 

stat = FDL$PARSE ( &fdl_file, &fab__ptr, &rab_ptr ); 
if (!(stat & 1)) LIB$STOP ( stat ); 

/* 

** Try to open file as described by information in the FAB. 

** Signal open errors. Note the usage of STAT, instead of 
** FAB__PTR->FAB$L_STS because just in case the FAB is invalid, 

** the only status returned is STAT. 

*/ 

stat = SYS$OPEN ( fab__ptr ) ; 

if (l(stat & 1)) LIB$STOP ( stat, fab_ptr->fab$l_stv ); 
stat = SYS$CONNECT ( rab_ptr ); 

if (l(stat & 1)) LIB$STOP ( stat, rab__ptr->rab$l_stv ); 

/* 

** Opened the file and connect some internal buffers. 

** Fill in the record output buffer information which is the only 
** missing information in the RAB that was created for us by FDL. 

** Print a header recod and perform the initial $GET. 

*/ 

rab_ptr->rab$w_usz = REC_SIZE; 
rab_ptr->rab$l_ubf = record_buffer; 

printf ("-start of records-\n"); 

stat = SYS$GET ( rab_ptr ); 

while (stat & 1) /* As long as the $GET is successful */ 

{ 

record_buffer[rab_ptr->rab$w_rsz] =0; /* Terminate for printf */ 

printf ("%s\n", record^buffer); /* Current record */ 

stat = SYS$GET ( rab_ptr ); /* Try to get next one */ 

} 

/* 

** At this point in the execution, the status should be EOF indicating 
** Successfully read the file to end. If not, signal real error. 

*/ 

if (stat != RMS$_EOF) LIB$STOP ( rab_ptr->rab$l_sts, rab_ptr->rab$l__stv ); 

printf ("-end of records-\n"); 

stat = SYS$CLOSE ( fab_ptr ); /* implicit $DISCONNECT */ 

if (l(stat & 1)) LIB$STOP ( fab_ptr->fab$l_sts, fab_ptr->fab$l_stv ); 

/* 

** Allow FDL to release the FAB and RAB structures and any other 
** structures (XAB) that it allocated on behalve of the program. 

** Return with its status as final status (succes or failure). 

*/ 

return FDL$RELEASE ( &fab_ptr, &rab_ptr ); 

} 
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Example 8-3 Using FDL$PARSE and FDL$GENERATE in a DEC Pascal 
Program 

[INHERIT ('SYS$LIBRARY:STARLET')] 

PROGRAM FDLexample {input,output,order_master); 

(* This program fills in its own FAB, RAB, and 
(* XABs by calling FDL$PARSE and then generates 
(* an FDL specification describing them. 

(* It requires an existing input FDL file 
(* (TESTING.FDL) for FDL$PARSE to parse. 

TYPE 
(*+ 

(* FDL CALL INTERFACE CONTROL FLAGS 
{*- 

$BIT1 = [BIT(1),UNSAFE] BOOLEAN; 

FDL2$TYPE = RECORD CASE INTEGER OF 
1: (FDL$_FDLDEF_BITS : [BYTE{1)] RECORD END; 

) ? 

2: (FDL$V_SIGNAL : [POS(O)] $BIT1; 

(* Signal errors; don't return *) 

FDL$V_FDL_STRING : [P0S{1)] $BIT1; 

{* Main FDL spec is a char string *) 

FDL$V_DEFAULT_STRING : [P0S{2)] $BIT1; 

(* Default FDL spec is a char string *) 
FDL$V_FULL_OUTPUT : [P0S(3)] $BIT1; 

(* Produce a complete FDL spec *) 

FDL$V_$CALLBACK : [P0S(4)] $BIT1; 

(* Used by EDIT/FDL on input (DEC only) *) 

) 

END; 

mail_order = RECORD 

order_num : [KEY(O)] INTEGER; 
name : PACKED ARRAY]1..20] OF CHAR; 
address : PACKED ARRAY[1..20] OF CHAR; 
city : PACKED ARRAY]1..19] OF CHAR; 

State : PACKED ARRAY]!..2] OF CHAR; 
zip_code : ]KEY(1)] PACKED ARRAY]!..5] 

OF CHAR; 

item_num : ]KEY(2)] INTEGER; 
shipping : REAL; 

END; 

order_file = ]UNSAFE] FILE OF mail_order; 
ptr_to_FAB = "FAB$TYPE; 
ptr_to_RAB = 'RAB$TYPE; 
byte = 0..255; 

VAR 

order_master : order_file; 
flags : FDL2$TYPE; 

order_rec : mail_order; 
temp_FAB : ptr_to_FAB; 
temp_RAB : ptr_to_RAB; 
status ! integer; 

FUNCTION FDL$PARSE 

(%STDESCR FDL_FILE : PACKED ARRAY ]L..UtINTEGER] 

OF CHAR; 

VAR FAB_PTR : PTR_TO_FAB; 

VAR RAB_PTR : PTR_TO_RAB) : INTEGER; EXTERN; 


(continued on next page) 


*) 

*) 

*) 

*) 

*) 

*) 

*) 
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Example 8-3 (Cent.) Using FDL$PARSE and FDL$GENERATE in a DEC Pascal 
Program 

FUNCTION FDL$GENERATE 

(%REF FLAGS : FDL2$TYPE; 

FAB__PTR : PTR__TO_FAB; 

RAB_PTR : PTR_TO_RAB; 

%STDESCR FDL__FILE__DST : PACKED ARRAY [L. .U:INTEGER] 

OF CHAR) ; INTEGER; 

EXTERN; 

BEGIN 

status := FDL$PARSE ('TESTING',TEMP__FAB,TEMP_RAB); 

flags::byte := 0; 

status := FDL$GENERATE (flags, 

temp_FAB, 
temp RAB, 

'SYS^OUTPUT:'); 

END. 


8.3 FDL Routines 

The following pages describe the individual FDL routines. 
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FDL$CREATE—Create a File from an FDL Specification and Close 
the File 

The FDL$CREATE routine creates a file from an FDL specification and then 
closes the file. 

Format 

FDL$CREATE fdLdesc [,filename] [,default_name] [,result_name] [,fid_block] [,flags] 
[,stmnt_num] [,retlen] [,sts] [,stv] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

fdLdesc 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 

Name of a file that contains the FDL specification or the actual FDL specification 
to be parsed. The fdLdesc argument is the address of a character string 
descriptor pointing to this information. 

If the FDL$V_FDL_STRING flag is set in the mask argument, FDL$CREATE 
interprets this argument as an FDL specification in string form. Otherwise, 
FDL$CREATE interprets this argument as a file name. 

filename 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 

Name of the OpenVMS RMS file to be created using the FDL specification. The 
filename argument is the address of a character string descriptor pointing to 
the OpenVMS RMS file name. This name overrides the default_name parameter 
given in the FDL specification. 

This argument is optional. 

defaulLname 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 
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Default name of the file to be created using the FDL specification. The default^ 
name argument is the address of a character string descriptor pointing to the 
default file name. This name overrides any name given in the FDL specification. 

This argument is optional. 

result_name 

OpenVMS usage char_string 

type character-coded text string 

access write only 

mechanism by descriptor—fixed-length string descriptor 

Resultant name of the file created by FDL$CREATE. The result_name argument 
is the address of a character string descriptor that receives the resultant file 
name. 

This argument is optional. 

fid_block 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

File identification of the OpenVMS RMS file created by FDL$CREATE. The 
fid_block argument is the address of an array of longwords that receives the 
OpenVMS RMS file identification information. The first longword contains the 
FID_NUM; the second contains the FID_SEQ; and the third contains the FID_ 
RVN. They have the following definitions: 

FID_NUM The location of the file on the disk. Its value can range from 1 up 
to the number of files the disk can hold. 

FID_SEQ The file sequence number, which is the number of times the file 
number has been used. 

FID_RVN The relative volume number, which is the volume number of the 
volume on which the file is stored. If the file is not stored on a 
volume set, the relative volume number is 0. 

This argument is optional. 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags (or masks) that control how the fdLdesc argument is interpreted and how 
errors are signaled. The flags argument is the address of a longword containing 
the control flags (or a mask). If you omit this argument or specify it as zero, no 
flags are set. The table that follows shows the flags and their meanings. 
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Flag 

Description 

FDL$V_FDL_STRING 

Interprets the fdl^desc argument as an FDL 
specification in string form. By default, the fdl_ 
desc argument is interpreted as the file name of an 
FDL file. 

FDL$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signaled. 

stmnt_num 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

FDL statement number. The stmnt_num argument is the address of a longword 
that receives the FDL statement number. If the routine completes successfully, 
the stmnt_num argument is the number of statements in the FDL specification. 
If the routine does not complete successfully, the stmnt_num argument receives 
the number of the statement that caused the error. In general, however, line 
numbers and statement numbers are not the same. Null statements (blank lines) 
are not counted. Also, an FDL specification in string form has no “lines.” 

This argument is optional. 

retlen 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Number of characters returned in the result_name argument. The retlen 
argument is the address of a longword that receives this number. 

This argument is optional. 

sts 

OpenVMS usage longword_unsigned 
type longword_unsigned 

access write only 

mechanism by reference 

OpenVMS RMS status value FAB$L_STS. The sts argument is the address of a 
longword that receives the status value FAB$L_STS from SYS$CREATE. 

stv 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

OpenVMS RMS status value FAB$L_STV. The stv argument is the address of a 
longword that receives the status value FAB$L_STV from SYS$CREATE. 
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Description 

FDL$CREATE calls the FDL$PARSE routine to parse the FDL specification. The 
FDL specification can be either in a file or a character string. FDL$CREATE 
opens (creates) the specified OpenVMS RMS file, and then closes it without 
putting any data in it. 

FDL$CREATE does not create the output file if an error status is either returned 
or signaled. 


Condition Values Returned 

SS$_NORMAL 

FDL$_ABKW 

FDL$_ABPRIKW 

FDL$_BADLOGIC 

FDL$_CLOSEIN 

FDL$_CLOSEOUT 

FDL$_CREATE 

FDL$_CREATED 

FDL$_CREATED_STM 

FDL$_FDLERROR 

FDL$_ILL_ARG 

FDL$_INSVIREM 

FDL$_INVBLK 

FDL$_MULPRI 

FDL$_OPENFDL 

FDL$_OPENIN 

FDL$_OPENOUT 

FDL$_OUTORDER 

FDL$_READERR 

FDL$_RFLOC 

FDL$_SYNTAX 

FDL$_UNPRIKW 

FDL$_UNQUAKW 

FDL$_UNSECKW 

FDL$_VALERR 


Normal successful completion. 

Ambiguous keyword in statement 
' number' <CRLF>' reference-text'. 

Ambiguous primary keyword in statement 
' number' <CRLF>' reference-text'. 

Internal logic error detected. 

Error closing ' filename' as input. 

Error closing ' filename' as output. 

Error creating ' filename'. 

'filename' created. 

' filename' created in stream format. 

Error parsing FDL file. 

Wrong number of arguments. 

Insufficient virtual memory. 

Invalid OpenVMS RMS control block at virtual 
address 'hex-offset'. 

Multiple primary definition in statement 
' number'. 

Error opening ' filename'. 

Error opening ' filename' as input. 

Error opening 'filename' as output. 

Key or area primary defined out of order in 
statement 'number'. 

Error reading ' filename'. 

Unable to locate related file. 

Syntax error in statement ' number' ' reference- 
text '. 

Unrecognized primary keyword in statement 
' number' <CRLF> ' reference-text'. 

Unrecognized qualifier keyword in statement 
' number' <CRLF> ' reference-text'. 

Unrecognized secondary keyword in statement 
' number' <CRLF> ' reference-text'. 

Specified value is out of legal range. 
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FDL$_VALPRI 

Value required on primary in statement 
' number'. 

FDL$_WARNING 

Parsed with warnings. 

FDL$_WRITEERR 

Error writing ' filename'. 

RMS$_ACT 

File activity precludes operation. 

RMS$_CRE 

ACP file create failed. 

RMS$_CREATED 

File was created, not opened. 

RMS$_DNF 

Directory not found. 

RMS$_DNR 

Device not ready or not mounted. 

RMS$_EXP 

File expiration date not yet reached. 

RMS$_FEX 

File already exists, not superseded. 

RMS$_FLK 

File currently locked by another user. 

RMS$_PRV 

Insufficient privilege or file protection violation. 

RMS$_SUPERSEDE 

Created file superseded existing version. 

RMS$_WLK 

Device currently write locked. 
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FDL$GENERATE—Generate an FDL Specification 

The FDL$GENERATE routine produces an FDL specification and writes it to 
either an FDL file or a character string. 


Format 


FDL$GENERATE flags ,fab_pointer ,rab_pointer [,fdLfile_dst] [,fdLfile_resnam] 
[,fdLstr_dst] [,bad_blk_addr] [,retlen] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags (or masks) that control how the fdLstr_dst argument is interpreted and 
how errors are signalled. The flags argument is the address of a longword 
containing the control flags (or a mask). If you omit this argument or specify it as 
zero, no flags are set. The flags and their meanings are as follows: 


Flag 

Description 

FDL$V_FDL_STRING 

Interprets the fdLstr_dst argument as an FDL 
specification in string form. By default, the fdLstr_ 
dst argument is interpreted as a file name of an 
FDL file. 

FDL$V_FULL_OUTPUT 

Includes the FDL attributes to describe all the bits 
and fields in the OpenVMS RMS control blocks, 
including run-time options. If this flag is set, every 
field is inspected before being written. By default, 
only the FDL attributes that describe permanent file 
attributes are included (producing a much shorter 
FDL specification). 

FDL$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signaled. 
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fab_pointer 

Open VMS usage 
type 
access 
mechanism 

OpenVMS RMS file access block (FAB). The fab__pointer argument is the address 
of a longword containing the address of a FAB. 

rab_pointer 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

OpenVMS RMS record access block (RAB). The rab__pointer argument is the 
address of a longword containing the address of a RAB. 

fdl_file_dst 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

Name of the FDL file to be created. The fdl_file_dst argument is the address of a 
character string descriptor containing the file name of the FDL file to be created. 
If the FDL$V_FDL_STRING fiag is set in the flags argument, this argument 
is ignored; otherwise, it is required. The FDL specification is written to the file 
named in this argument. 

fdl_file_resnam 

OpenVMS usage char_string 

type character-coded text string 

access write only 

mechanism by descriptor—fixed-length string descriptor 

Resultant name of the FDL file created. The fdl_file_resnam argument is the 
address of a variable character string descriptor that receives the resultant name 
of the FDL file created (if FDL$GENERATE is directed to create an FDL file). 

This argument is optional. 

fdLstr_dst 

OpenVMS usage char_string 

type character-coded text string 

access write only 

mechanism by descriptor—fixed-length string descriptor 

FDL specification. The fdLstr_dst argument is the address of a variable 
character string descriptor that receives the FDL specification created. If the 
FDL$V_FDL_STRING bit is set in the flags argument, this argument is required; 
otherwise, it is ignored. 

bad_blk_addr 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 


address 

longword (unsigned) 
read only 
by reference 
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Address of an invalid OpenVMS RMS control block. The bad_blk_addr 
argument is the address of a longword that receives the address of an invalid 
control block. If an invalid control block (a fatal error) is detected, this argument 
is returned; otherwise, it is ignored. 

This argument is optional. 

retlen 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Number of characters received in either the fdl_file_resnam or the fdLstr_dst 
argument. The retlen argument is the address of a longword that receives this 
number. 

Condition Values Returned 


SS$_NORMAL 

Normal successful completion. 

FDL$_INVBLK 

Invalid 

RMS$_ACT 

File activity precludes operation. 

RMS$_CONTROLC 

Operation completed under CTRL/C. 

RMS$_CONTROLO 

Output completed under CTRL/O. 

RMS$_CONTROLY 

Operation completed under CTRLA^. 

RMS$_DNR 

Device not ready or mounted. 

RMS$_EXT 

AGP file extend failed. 

RMS$_OK_ALK 

Record already locked. 

RMS$_OK_DUP 

Record inserted had duplicate key. 

RMS$_OK_IDX 

Index update error occurred. 

RMS$_PENDING 

Asynchronous operation pending completion. 

RMS$_PRV 

Insufficient privilege or file protection violation. 

RMS$_REX 

Record already exists. 

RMS$_RLK 

Target record currently locked by another 
stream. 

RMS$_RSA 

Record stream currently active. 

RMS$_WLK 

Device currently write locked. 

SS$_ACCVIO 

Access violation. 

STR$_FATINERR 

Fatal internal error in Run-Time Library. 

STR$_ILLSTRCLA 

Illegal string class. 

STR$_INSVIRMEM 

Insufficient virtual memory. 
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FDL$PARSE—Parse an FDL Specification 

The FDL$PARSE routine parses an FDL specification, allocates OpenVMS RMS 
control blocks (FABs, RABs, or XABs), and fills in the relevant fields. 

Format 

FDL$PARSE fdLspec ,fdLfab_pointer ,fdLrab_pointer [,flags] [,dflt_fdLspc] 
[,stmnt_num] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

fdLspec 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 

Name of the FDL file or the actual FDL specification to be parsed. The fdl_ 
spec argument is the address of a character string descriptor pointing to either 
the name of the FDL file or the actual FDL specification to be parsed. If the 
FDL$V_FDL_STRING flag is set in the flags argument, FDL$PARSE interprets 
this argument as an FDL specification in string form. Otherwise, FDL$PARSE 
interprets this argument as a file name of an FDL file. 

fdl_fab_pointer 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Address of an OpenVMS RMS file access block (FAB). The fdl_fab_pointer 
argument is the address of a longword that receives the address of the FAB. 
FDL$PARSE both allocates the FAB and fills in its relevant fields. 

fdl_rab_pointer 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Address of an OpenVMS RMS record access block (RAB). The fdLrab_pointer 
argument is the address of a longword that receives the address of the RAB. 
FDL$PARSE both allocates the RAB and fills in its relevant fields. 
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flags 

OpenVMS usage 

type 

access 

mechanism 


mask_longword 
longword (unsigned) 
read only 
by reference 


Flags (or masks) that control how the dflt_fdl_spc argument is interpreted 
and how errors are signaled. The flags argument is the address of a longword 
containing the control flags. If you omit this argument or specify it as zero, no 
flags are set. The flags and their meanings are as follows: 


Flag 

Description 

FDL$V_DEFAULT_STRING 

Interprets the dflt_fdl_spc argument as an 
FDL specification in string form. By default, 
the dflt_fdl__spc argument is interpreted as a 
file name of an FDL file. 

FDL$V_FDL_STRING 

Interprets the fdl__spec argument as an FDL 
specification in string form. By default, the fdl_ 
spec argument is interpreted as a file name of 
an FDL file. 

FDL$V_SIGNAL 

Signals any error. By default, the status code is 
returned to the calling image. 


This argument is optional. By default, an error status is returned rather than 
signaled. 

dflt_fdl_spc 

OpenVMS usage char_string 

type character-coded text string 

access read only 

mechanism by descriptor—fixed-length string descriptor 

Name of the default FDL file or the default FDL specification itself. The dflt_fdl_ 
spc argument is the address of a character string descriptor pointing to either 
the default FDL file or the default FDL specification. If the FDL$V_DEFAULT_ 
STRING flag is set in the flags argument, FDL$PARSE interprets this argument 
as an FDL specification in string form. Otherwise, FDL$PARSE interprets this 
argument as a file name of an FDL file. 

This argument allows you to specify default FDL attributes. In other words, 
FDL$PARSE processes the attributes specified in this argument, unless you 
override them with the attributes you specify in the fdl_spec argument. 

You can code the FDL defaults directly into your program, typically with an FDL 
specification in string form. 

This argument is optional. 

stmnt_num 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

FDL statement number. The stmnt__num argument is the address of a longword 
that receives the FDL statement number. If the routine completes successfully. 
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the stmnt_num argument is the number of statements in the FDL specification. 
If the routine does not complete successfully, the stmnt_num argument receives 
the number of the statement that caused the error. In general, however, line 
numbers and statement numbers are not the same. 

This argument is optional. By default, an error status is returned rather than 
signaled. 


Normal successful completion. 

Bad block address. 

Bad block size. 

Insufficient virtual memory. 

Directory not found. 

Device not ready or not mounted. 
Invalid wildcard context (WCC) value. 


Condition Values Returned 

SS$_NORMAL 

LIB$_BADBLOADR 

LIB$_BADBLOSIZ 

LIB$_INSVIRMEM 

RMS$_DNF 

RMS$_DNR 

RMS$_WCC 
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FDL$RELEASE—Free Virtual Memory Obtained By FDL$PARSE 

The FDL$RELEASE routine deallocates the virtual memory used by the 
OpenVMS RMS control blocks created by FDL$PARSE. You must use 
FDL$PARSE to populate the control blocks if you plan to deallocate memory 
with FDL$RELEASE later. 


Format 

FDL$RELEASE [fab_pointer] [,rab_pointer] [,flags] [,badblk_addr] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

fab_pointer 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

File access block (FAB) to be deallocated using the LIB$FREE_VM system 
service. The fab_pointer argument is the address of a longword containing the 
address of the file access block (FAB). The FAB must be the same one returned 
by the FDL$PARSE routine. Any name blocks (NAMs) and extended attribute 
blocks (XABs) connected to the FAB are also released. 

This argument is optional. If you omit this argument or specify it as zero, the 
FAB (and any associated NAM blocks and XABs) is not released. 

rab_pointer 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Record access block (RAB) to be deallocated using the LIB$FREE_VM system 
service. The rab_pointer argument is the address of a longword containing the 
address of the record access block (RAB). The address of the RAB must be the 
same one returned by the FDL$PARSE routine. Any XABs connected to the RAB 
are also released. 

This argument is optional. If you omit this argument or specify it as zero, the 
RAB (and any associated XABs) is not released. 
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flags 

OpenVMS usage 
type 
access 
mechanism 

Flag (or mask) that controls how errors are signalled. The flags argument is the 
address of a longword containing the control flag (or a mask). If you omit this 
argument or specify it as zero, no flag is set. The flag is deflned as follows: 

FDL$V_SIGNAL Signals any error. By default, the status code is returned to 
the calling image. 

This argument is optional. 

badblk_addr 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Address of an invalid OpenVMS RMS control block. The badblk_addr argument 
is the address of a longword that receives the address of an invalid control block. 
If an invalid control block (a fatal error) is detected, this argument is returned; 
otherwise, it is ignored. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

FDL$_INVBLK Invalid VMS RMS control block at virtual 

address 'hex-offset'. 

LIB$_BADBLOADR Bad block address. 

RMS$_ACT File activity precludes operation. 

RMS$_RNL Record not locked. 

RMS$_RSA Record stream currently active. 

SS$_ACCVIO Access violation. 


mask_longword 
longword (unsigned) 
read only 
by reference 
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Librarian (LBR) Routines 


The LBR routines let you create and maintain libraries and their modules, 
and use the data stored in library modules. You can also create and maintain 
libraries at the DCL level, using the DCL command LIBRARY. For details, see 
the OpenVMS DCL Dictionary. 

9.1 Introduction to LBR Routines 

Section 9.1.1 briefly describes the types of libraries you can create and maintain 
using LBR routines and how the libraries are structured. This section also lists 
and briefly describes the LBR routines. Section 9.2 provides sample programs 
showing how to use various LBR routines. Section 9.3 is a reference section that 
provides details about each of the LBR routines. 

9.1.1 Types of Libraries 

You can use the LBR routines to maintain the following types of libraries: 

• Object libraries, including AXP object libraries, which contain the object 
modules of frequently called routines. The Linker utility searches specifled 
object module libraries when it encounters a reference it cannot resolve in one 
of its input flies. For more information about how the linker uses libraries, 
see the description of the Linker utility in the OpenVMS Linker Utility 
Manual. 

An object library has a default file type of .OLB and defaults the file type of 
input files to .OBJ. 

• Macro libraries, which contain macro definitions used as input to the 
assembler. The assembler searches specifled macro libraries when it 
encounters a macro that is not defined in the input file. See the VAX MACRO 
and Instruction Set Reference Manual for information about defining macros. 

A macro library has a default file type of .MLB and defaults the file type of 
input files to .MAR. 

• Help libraries, which contain modules of help messages that provide user 
information about a program. You can retrieve help messages at DCL level 
by executing the DCL command HELP, or in your program by calling the 
appropriate LBR routines. For information about creating help modules for 
insertion into help libraries, see the description of the Librarian utility in the 
OpenVMS Command Definition, Librarian, and Message Utilities Manual. 

A help library has a default file type of .HLB and defaults the file type of 
input files to .HLP. 

• Text libraries, which contain any sequential record files that you want to 
retrieve as data for a program. For example, some compilers can retrieve 
program source code from text libraries. Each text file inserted into the 
library corresponds to one library module. Your programs can retrieve text 
from text libraries by calling the appropriate LBR routines. 
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A text library has a default file type of .TLB and defaults the file type of input 
files to .TXT. 

• Shareable image libraries and AXP shareable symbol table libraries which 
contain the symbol tables of shareable images used as input to the linker. 

For information about how to create a shareable image library, see the 
descriptions of the Librarian and Linker utilities in the OpenVMS Command 
Definition, Librarian, and Message Utilities Manual and the OpenVMS Linker 
Utility Manual. 

A shareable image library has a default type of .OLB and defaults the file 
type of input files to .EXE. 

• National character set (NCS) libraries, which contain definition modules that 
define collating sequences and conversion functions. NCS libraries have the 
default file type .NLB. For information about how to create a NCS library, see 
the OpenVMS National Character Set Utility Manual. 

• User-developed libraries, which have characteristics specified when you call 
the LBR$OPEN routine to create a new library. User-developed libraries 
allow you to use the LBR routines to create and maintain libraries that are 
not structured in the form assigned by default to the other library types. Note 
that you cannot use the DCL command LIBRARY to access user-developed 
libraries. 

9.1.2 Structure of Libraries 

You create libraries by executing the DCL command LIBRARY or by calling the 
LBR$OPEN routine. When object, macro, text, help, or shareable image libraries 
are created, the Librarian utility structures them as described in Figures 9—1 and 
9—2. You can create user-developed libraries only by calling LBR$OPEN; they are 
structured as described in Figure 9—3. 

9.1.2.1 Library Headers 

Every library contains a library header that describes the contents of the library, 
for example, its type, size, version number, creation date, and number of indexes. 
You can retrieve data from a library’s header by calling the LBR$GET_HEADER 
routine. 

9.1.2.2 Modules 

Each library module consists of a header and data. The data is the data you 
inserted into the library; the header associated with the data is created by the 
LBR routine and provides information about the module, including its type, 
attributes, and date of insertion into the library. You can read and update a 
module’s header by calling the LBR$SET_MODULE routine. 

9.1.2.3 Indexes and Keys 

Libraries contain one or more indexes, which can be thought of as directories of 
the library’s modules. The entries in each index are keys, and each key consists 
of a key name and a module reference. The module reference is a pointer to the 
module’s header record and is called that record’s file address (RFA). Macro, text, 
and help libraries (see Figure 9—1) contain only one index, called the module 
name table. The names of the keys in the index are the names of the modules in 
the library. 
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Object and shareable image libraries (see Figure 9-2) contain two indexes: the 
module name table and a global symbol table. The global symbol table consists of 
all the global symbols defined in the modules in the library. Each global symbol 
is a key in the index and points to the module in which it was defined. 

If you need to point to the same module with several keys, you should create a 
user-developed library, which can have up to eight indexes (see Figure 9—3). Each 
index consists of keys that point to the library’s modules. 

The LBR routines differentiate library indexes by numbering them, starting with 
1. For all but user-developed libraries, the module name table is index number 
1 and the global symbol table, if present, is index number 2. You number the 
indexes in user-developed libraries. When you access libraries that contain more 
than one index, you may have to call LBR$SET_INDEX to tell the LBR routines 
which index to use. 


Figure 9-1 Structure of a Macro, Text, or Help Library 
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Figure 9-2 Structure of an Object or Shareable Image Library 
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Figure 9-3 Structure of a User-Developed Library 
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9.1.3 Summary of LBR Routines 

All the LBR routines begin with the characters LBR$. Your programs can call 
these routines by using the OpenVMS Calling Standard. When you call a LBR 
routine, you must provide all required arguments. Upon completion, the routine 
returns its completion status as a condition value. In addition to the listed 
condition values, some routines may return the success code SS$_NORMAL as 
well as various RMS or system status (SS) error codes. 

When you link programs that contain calls to LBR routines, the linker locates the 
routines during its default search of SYS$SHARE:LBRSHR. Table 9—1 lists the 
routines and summarizes their functions. 
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Table 9-1 LBR Routines 
Routine Name Function 


LBR$CLOSE 

LBR$DELETE_DATA 

LBR$DELETE_KEY 

LBR$FIND 

LBR$FLUSH 

LBR$GET_HEADER 

LBR$GET_HELP 

LBR$GET_HISTORY 

LBR$GET_INDEX 

LBR$GET_RECORD 

LBR$INI_CONTROL 

LBR$INSERT_KEY 

LBR$LOOKUP_KEY 

LBR$OPEN 

LBR$OUTPUT_HELP 

LBR$PUT_END 

LBR$PUT_HISTORY 

lbr$put_record 

LBR$REPLACE_KEY 

LBR$RET_RMSSTV 

LBR$SEARCH 

LBR$SET_INDEX 

LBR$SET_LOCATE 

LBR$SET_MODULE 

LBR$SET_MOVE 


Closes an open library. 

Deletes a specified module’s header and data. 

Deletes a key from a library index. 

Finds a module by using an address returned by a preceding 
call to LBR$LOOKUP_KEY. 

Writes the contents of modified blocks to the library file and 
returns the virtual memory that contained those blocks. 

Retrieves information from the library header. 

Retrieves help text from a specified library. 

Retrieves library update history records and calls a user- 
supplied routine with each record returned. 

Calls a routine to process modules associated with some or 
all of the keys in an index. 

Reads a data record from the module associated with a 
specified key. 

Initializes a control index that the librarian uses to identify a 
library. 

Inserts a new key in the current library index. 

Looks up a key in the current index. 

Opens an existing library or creates a new one. 

Retrieves help text from an explicitly named library or from 
user-supplied default libraries, and optionally prompts you 
for additional help queries. 

Terminates the writing of a sequence of records to a module 
using the LBR$PUT_RECORD routine. 

Inserts a library update history record. 

Writes a data record to the module associated with the 
specified key. 

Replaces an existing key in the current library index. 

Returns the last RMS status value. 

Finds index keys that point to specified data. 

Sets the index number to be used during processing of the 
library. 

Sets librarian subroutine record access to locate mode. 

Reads and optionally updates a module header. 

Sets librarian subroutine record access to move mode. 


9.2 Using the LBR Routines 

This section provides programming examples that call LBR$ routines. Although 
the examples do not illustrate all the LBR routines, they do provide an 
introduction to the various data structures and the calling syntax. 

The program examples are written in DEC Pascal and the subroutine examples 
are written in DEC Fortran. The listing of each program example contains 
comments and is followed by notes about the program. The highlighted numbers 
in the notes are keyed to the highlighted numbers in the examples. 
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Each of the sample programs calls the LBR$INI_CONTROL routine and the 
LBR$OPEN routine before calling any other routine. 

_ Note _ 

The one exception is that when you call the LBR$OUTPUT_HELP 
routine, you need not call the LBR$INI_CONTROL routine and the 
LBR$OPEN routine. 


The sample programs require access to various symbols derived from definition 
macros. Use the INHERIT attribute to access these symbols from definition 
macros in SYS$LIBRARY:STARLET.PEN. 

The LBR$INI_CONTROL routine sets up a control index; do not confuse this 
with a library index. The control index is used in subsequent LBR routine calls 
to identify the applicable library (because you may want your program to work 
with more than one library at a time). 


_ Note 

Do not alter the control index value. 


LBR$INI_CONTROL specifies the library function, which can be to either create 
and update a new library (LIB$C_CREATE), modify an existing library (LIB$C_ 
UPDATE), or read an existing library without updating it (LIB$C_READ). 

Upon completion of the LBR$INI_CONTROL routine, call the LBR$OPEN 
routine to open the library. Open an existing library, or create and open a new 
library, in either the UPDATE or READ mode, checking for an error status value 
of RMS$_FNF. If this error occurs, open the library in CREATE mode. 

When you open the library, specify the library type and pass the file specification 
or partial file specification of the library file. 

If you are creating a new library, pass the create options array. The CRE$ 
symbols identify the significant longwords of the array by their byte offsets into 
the array. Convert these values to subscripts for an array of integers (longwords) 
by dividing by 4 and adding 1. If you do not load the significant longwords before 
calling LBR$INI_CONTROL, the library may be corrupted upon creation. 

Finally, pass any defaults for the file specification. If you omit the device and 
directory parts of the file specification, the current default device and directory 
are used. 

When you finish working with a library, call LBR$CLOSE to close the library 
by providing the control index value. You must close a library explicitly before 
updates can be posted. Remember to call LBR$INI_CONTROL again if you want 
to reopen the library. LBR$CLOSE deallocates all the memory associated with 
the library, including the control index. 

The order in which you call the routines between LBR$OPEN and LBR$CLOSE 
depends upon the library operations you need to perform. You may want to call 
LBR$LOOKUP_KEY or LBR$GET_INDEX to find a key, then perform some 
operation on the module associated with the key. You can think of a module as 
being both the module itself and its associated keys. To access a module, you first 
need to access a key that points to it; to delete a module, you first need to delete 
any keys that point to it. 
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_ Note _ 

Do not use LBR$INI_CONTROL, LBR$OPEN, and LBR$CLOSE 
for writing help text with LBR$OUTPUT_HELR Simply invoke 
LBR$OUTPUT_HELP 


9.2.1 Creating, Opening, and Closing a Text Library 

Example 9-1 is a sample DEC Pascal program that creates, opens, and then 
closes a text library. The program is summarized in the following steps: 

1. Initialize the library—Call LBR$INI_CONTROL to initialize the library. 

2. Open the library—Call LBR$OPEN to open the library. 

3. Close the library—Call LBR$CLOSE to close the library. 


Example 9-1 Creating a New Library Using DEC Pascal 

PROGRAM createlib(INPUT,OUTPUT); 

(*This program creates a text library*) 

TYPE (*Data type of*) 

Create_Array = ARRAY [1..20] OF INTEGER; (*create options array*) 

VAR (*Constants and return status error 

codes for LBR$__OPEN & LBR$INI_CONTROL. 
These are defined in $LBRDEF macro*) 
LBR$C_CREATE,LBR$C_TYP_TXT,LBR$_ILLCREOPT,LBR$_ILLCTL, O 

LBR$_ILLFMT,LBR$_NOFILNAM,LBR$_OLDMISMCH,LBR$_TYPMISMCH : 

[EXTERNAL] INTEGER; 

(*Create options array codes. These 
are defined in $CREDEF macro*) 

CRE$L_TYPE,CRE$L_KEYLEN,CRE$L_ALLOC,CRE$L_IDXMAX,CRE$L_ENTALL, 
CRE$L_LUHMAX,CRE$L_VERTYP,CRE$L_IDXOPT,CRE$C_MACTXTCAS, 

CRE$C_VMSV3 : [EXTERNAL]INTEGER; 

Lib_Name : VARYING [128] OF CHAR; (*Name of library to create*) 

Options : Create_Array; (*Create options array*) 

File_Type : PACKED ARRAY [1..4] (*Character string that is default*) 


OF CHAR := '.TLB' 
lib_index_ptr : UNSIGNED; 
status : UNSIGNED; 


(*file type of created lib file*) 
(*Value returned in library init*) 
(*Return Status for function calls*) 

(*_*-*_*_Function and Procedure Definitions-*-*-*-*) 

(*Function that returns library 
control index used by librarian*) 
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; © 

func: UNSIGNED; 
typ: UNSIGNED; 

VAR namblk: ARRAY[1..u:INTEGER] 

OF INTEGER := %IMMED 0): 

INTEGER; EXTERN; 

{♦Function that creates/opens library*) 
FUNCTION LBR$OPEN (library_index: UNSIGNED; 

fns: [class_s]PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create_options: Create_Array; 

dns: [CLASS_S] PACKED ARRAY [13..u3:INTEGER] OF CHAR; 
rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
%IMMED 0; 

VAR rnslen: INTEGER := %IMMED 0): 

INTEGER; EXTERN; 


(continued on next page) 
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Example 9-1 (Cent.) Creating a New Library Using DEC Pascai 

(*Function that closes library*) 
FUNCTION LBR$CLOSE (library^index: UNSIGNED): 

INTEGER; EXTERN; 

(*Error handler to check error codes 
if open/create not successful*) 

PROCEDURE Open_Error; © 

BEGIN 

WRITELN{'Open Not Successful'); {*Now check specific error codes*) 

IF status = IADDRESS{LBR$_ILLCREOPT) THEN 

WRITELN(' Create Options Not Valid Or Not Supplied'); 

IF status = IADDRESS(LBR$_ILLCTL) THEN 
WRITELN{' Invalid Library Index'); 

IF status = IADDRESS(LBR$_ILLFMT) THEN 

WRITELN(' Library Not In Correct Format'); 

IF status = IADDRESS(LBR$_NOFILNAM) THEN 

WRITELN(' Library Name Not Supplied'); 

IF status = IADDRESS(LBR$_OLDMISMCH) THEN 
WRITELN(' Old Library Conflict'); 

IF status = IADDRESS(LBR$_TYPMISMCH) THEN 
WRITELN(' Library Type Mismatch') 

END; (*of procedure Open_Error*) 

BEGIN (* *************** DECLARATIONS COMPLETE ************************* 
*************** MAIN PROGRAM BEGINS HERE ********************** *) 

{*Prompt for Library Name*) 

WRITE('Library Name: '); READLN(Lib_Name); 

{♦Fill Create Options Array. Divide 
by 4 and add 1 to get proper subscript*) 
Options[IADDRESS(CRE$L_TyPE) DIV 4+1] := IADDRESS(LBR$C_TYP_TXT); 

Options[IADDRESS(CRE$L_KEYLEN) DIV 4 + 1] := 31; O 
Options[IADDRESS(CRE$L_ALLOC) DIV 4 + 1] :=8; 

Options[IADDRESS(CRE$L_IDXMAX) DIV 4 + 1] :=1; 

Options[IADDRESS(CRE$L_ENTALL) DIV 4 + 1] := 96; 

Options[IADDRESS(CRE$L_LUHMAX) DIV 4 + 1] := 20; 

Options[IADDRESS(CRE$L_VERTYP) DIV 4+1] := IADDRESS(CRE$C_VMSV3); 

Options[IADDRESS(CRE$L_IDXOPT) DIV 4+1] := IADDRESS(CRE$C_MACTXTCAS); 

(*Initialize library control index*) 
status := LBR$INI_CONTROL (lib_index_ptr, @ 

IADDRESS(LBR$C_CREATE), (*Create access*) 
IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 

IF NOT ODD(status) THEN (*Check return status*) 

WRITELN('Initialization Failed') 

ELSE (*Initialization was successful*) 

BEGIN (*Create and open the library*) 

status := LBR$OPEN (lib_index_ptr, 

Lib__Name, 

Options, © 

File_Type); 

IF NOT ODD(status) THEN (*Check return status*) 

Open^Error (*Call error handler*) O 

ELSE (*Open/create was successful*) 

BEGIN (*Close the library*) 

status := LBR$CLOSE(lib_index_ptr); 

IF NOT ODD(status) THEN (*Check return status*) 

WRITELN('Close Not Successful') 

END 

END 

END. (*of program creatlib*) 
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Each item in the following list corresponds to a number highlighted in 
Example 9—1: 

O Use the INHERIT attribute to access the LBR$ and CRE$ symbols from 
SYS$LIBRARY:STARLET.PEN. 

© Start the declarations of the LBR routines that are used by the program. 
Each argument to be passed to the librarian is specified on a separate line 
and includes the name (which just acts as a placeholder) and data type (for 
example: UNSIGNED, which means an unsigned integer value, and PACKED 
ARRAY OF CHAR, which means a character string). If the argument is 
preceded by VAR, then a value for that argument is returned by the LBR to 
the program. 

0 Declare the procedure Open_Error, which is called in the executable section if 
the librarian returns an error when LBR$OPEN is called. Open_Error checks 
the librarian’s return status value to determine the specific cause of the error. 
The return status values for each routine are listed in the descriptions of the 
routines. 

O Initialize the array called Options with the values the librarian needs to 
create the library. 

@ Call LBR$INI_CONTROL, specifying that the function to be performed is 
create and that the library type is text. 

© Call LBR$OPEN to create and open the library; pass the Options array 
initialized in item 5 to the librarian. 

O If the call to LBR$OPEN was unsuccessful, call the procedure Open_Error 
(see item 4) to determine the cause of the error. 

9.2.2 Inserting a Module 

Example 9—2 illustrates the insertion of a module into a library from a DEC 
Pascal program. The program is summarized in the following steps: 

1. LBR$LOOKUP_KEY (optional)—Ensure that the module does not already 
exist by calling LBR$LOOKUP_KEY. The return status should be LBR$_ 
KEYNOTFND. 

2. LBR$PUT_RECORD—Construct the module by calling LBR$PUT_RECORD 
once for each record going into the module. Pass the contents of the record 
as the second argument. LBR$PUT_RECORD returns the record file 
address (RFA) in the library file as the third argument on the first call. 

On subsequent calls, you pass the RFA as the third argument, so do not alter 
its value between calls. 

3. LBR$PUT_END—Call LBR$PUT_END after the last call to LBR$PUT_ 
RECORD. 

4. LBR$INSERT_KEY—Call LBR$INSERT_KEY to catalog the records you have 
just put in the library. The second argument is the name of the module. 

To replace an existing module, save the RFA of the module header returned by 
LBR$LOOKUP_KEY in step 1 in one variable and the new RFA returned by the 
first call to LBR$PUT_RECORD (step 2) in another variable. In step 4, invoke 
LBR$REPLACE_KEY instead of LBR$INSERT_KEY, pass the old RFA as the 
third argument, and the new RFA as the fourth argument. 
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Example 9-2 Inserting a Module into a Library Using DEC Pascai 


PROGRAM insertmod(INPUT,OUTPUT); 

(*This program inserts a module into a library*) 

TYPE 

Rfa_Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 

VAR 


LBR$C_UPDATE, (*ConstantS for LBR$INI_CONTROL*) 

LBR$C_TYP_TXT, (*Defined in $LBRDEF macro*) 

LBR$_KEYNOTFND : [EXTERNAL] INTEGER;(*Error code for LBR$LOOKUP_KEY*) 
Lib_Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module_Name : VARYING [31] OF CHAR; (*Name of module to insert*) 

Text Data_Record : VARYING [255] OF CHAR; {*Record in new module*) 

Textln : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 
lib_index_ptr : UNSIGNED; (*Value returned in library init*) 

status : UNSIGNED; (*Return status for function calls*) 

txtrfa_ptr : Rfa_Ptr; (*For key lookup and insertion*) 

Key_Not_Found : BOOLEAN := FALSE; (*True if new mod not already in lib*) 
(*-*-*-*-Function Definitions-*-*-*-*) 

(*Function that returns library 
control index used by librarian*) 
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; 

func: UNSIGNED; 
typ: UNSIGNED; 

VAR namblk: ARRAY]1..u:INTEGER] 

OF INTEGER := %IMMED 0): 


INTEGER; EXTERN; 


(*Function that creates/opens library*) 
FUNCTION LBR$OPEN (library_index: UNSIGNED; 

fns: [class_S]PACKED ARRAy[l..u:INTEGER] OF CHAR; 
create_options: ARRAY [12..u2:INTEGER] OF INTEGER := 

%IMMED 0; 

dns: [CLASS_S] PACKED ARRAY [ 13..u3:INTEGER] OF CHAR 
:= IIMMED 0; 

rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
%IMMED 0; 


VAR rnslen: INTEGER := DIMMED 0): 


INTEGER; EXTERN; 

(*Function 

FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED; 

key_name:[CLASS_S] PACKED 
CHAR; 

VAR txtrfa: Rfa_Ptr): 

INTEGER; EXTERN; 

(*Function 

FUNCTION LBR$INSERT_KEY (library_index: UNSIGNED; 

key_name:[CLASS_S] PACKED 
CHAR; 

txtrfa: Rfa_Ptr): 

INTEGER; EXTERN; 

(*Function 


that finds a key in index*) 
ARRAY [1..u:INTEGER] OF 


that inserts key in index*) 
ARRAY [1..u:INTEGER] OF 


that writes data records*) 


(continued on next page) 
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Example 9-2 (Cont.) Inserting a Module into a Library Using DEC Pascal 

FUNCTION LBR$PUT_RECORD (library_index: UNSIGNED; (*to modules*) 

textline:[CLASS_S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 

txtrfa: Rfa_Ptr): 

INTEGER; EXTERN; 

(^Function that marks end of a module*) 
FUNCTION LBR$PUT_END (library_index: UNSIGNED); 

INTEGER; EXTERN; 

(*Function that closes library*) 
FUNCTION LBR$CLOSE (library_index: UNSIGNED); 

INTEGER; EXTERN; 

BEGIN (* *************** DECLARATIONS COMPLETE ************************* 

*************** main program begins here ********************** *) 

(^Prompt for library name and 
module to insert*) 

WRITE('Library Name; '); READLN(Lib_Name); 

WRITE('Module Name; '); READLN(Module^Name); 

(*Initialize lib for update access*) 
status := LBR$INI_CONTROL (lib_index_ptr, O 

IADDRESS(LBR$C_UPDATE), (*Update access*) 
IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 

IF NOT ODD(status) THEN (*Check error status*) 

WRITELN('Initialization Failed') 

ELSE (*Initialization was successful*) 

BEGIN 

status ;= LBR$OPEN (lib_index_ptr, (*Open the library*) 

Lib_Name); 

IF NOT ODD(status) THEN (*Check error status*) 

WRITELN('Open Not Successful') 

ELSE (*Open was successful*) 

BEGIN (*Is module already in the library?*) 

status := LBR$LOOKUP_KEY (lib_index_ptr, © 

Module_Name, 
txtrfa__ptr); 

IF ODD(status) THEN (*Check status. Should not be odd*) 
WRITELN('Lookup key was successful.', 

'The module is already in the library.') 

ELSE (*Did lookup key fail because key not found?*) 

IF status = IADDRESS(LBR$_KEYNOTFND) THEN © 
Key_Not_Found := TRUE 

END 

END; 


(continued on next page) 
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Example 9-2 (Cent.) Inserting a Module into a Library Using DEC Pascai 

(******If lbr$LOOKUP_KEY failed because the key was not found 
(as expected), we can open the file containing the new module, 
and write the module's records to the library file*******) 

IF Key__Not_Found THEN 
BEGIN 

OPEN(Textin,Module_Name,old); 

RESET(Textin); 

WHILE NOT EOF(Textin) DO (*Repeat until end of file*) 

BEGIN O 

READ(Textin,Text__Data_Record); (*Read record from 

external file*) 

status := LBR$PUT_RECORD (lib_index_ptr, (*Write*) 

Text_Data_Record, (*record to*) 
txtrfa_ptr); (*library*) 

IF NOT ODD(status) THEN 

WRITELN('Put Record Routine Not Successful') 

END; (*of WHILE statement*) 

IF ODD(status) THEN (*True if all the records have been 

successfully written into the library*) 

BEGIN 

status := LBR$PUT_END (lib_index_ptr); (*Write end of 

module record*) 

IF NOT ODD(status) THEN 

WRITELN('Put End Routine Not Successful') 

ELSE (*Insert key for new module*) 

BEGIN © 

status ;= LBR$INSERT_KEY (lib_index__ptr, 

Module__Name, 
txtrfa_ptr); 

IF NOT ODD(status) THEN 

WRITELN('Insert Key Not Successful') 

END 

END 

END; 

status := LBR$CLOSE(lib_index_ptr); 

IF NOT ODD(status) THEN 

WRITELN('Close Not Successful') 

END. (*of program insertmod*) 

Each item in the following list corresponds to a number highlighted in 
Example 9—2. 

O Call LBR$INI_CONTROL, specifying that the function to be performed is 
update and that the library type is text. 

0 Call LBR$LOOKUP_KEY to see whether the module to be inserted is already 
in the library. 

0 Call LBR$LOOKUP_KEY to see whether the lookup key failed because the 
key was not found. (In this case, the status value is LBR$_KEYNOTFND.) 

O Read a record from the input file, then use LBR$PUT_RECORD to write the 
record to the library. When all the records have been written to the library, 
use LBR$PUT_END to write an end of module record. 

© Use LBR$INSERT_KEY to insert a key for the module into the current index. 
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9.2.3 Extracting a Module 

Example 9—3 illustrates the extraction of a library module from a DEC Pascal 

program. The program is summarized in the following steps: 

1. LBR$LOOKUP_KEY—Call LBR$LOOKUP_KEY to locate the module. 
Specify the name of the module as the second argument. LBR$LOOKUP_ 
KEY returns the RFA of the module as the third argument; do not alter this 
value. 

2. LBR$GET_RECORD—Call LBR$GET_RECORD once for each record in the 
module. Specify a character string to receive the extracted record as the 
second argument. LBR$GET_RECORD returns a status value of RMS$_EOF 
after the last record in the module is extracted. 


Example 9-3 Extracting a Module from a Library Using DEC Pascal 


PROGRAM extractmod(INPUT,OUTPUT,Textout); 

(*This program extracts a module from a library*) 

TYPE 

Rfa Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 


VAR 


LBR$C_UPDATE, 

LBR$C_TYP_TXT, 

RMS$_EOF : [EXTERNAL] INTEGER; 

Lib_Name : VARYING [128] OF CHAR; 
Module_Name : VARYING [31] OF CHAR; 
Extracted File : VARYING [31] OF CHAR; 


(*Constants for LBR$INI_CONTROL*) 
(*Defined in $LBRDEF macro*) 

(*RMS return status; defined in 
$RMSDEF macro*) 

(*Name of library receiving module*) 
(*Name of module to insert*) 


Outtext : PACKED ARRAY [1..255] OF CHAR; 
0uttext2 : VARYING [255] OF CHAR; 
i : INTEGER; 

Textout : FILE OF VARYING 

nullstring : CHAR; 
pos, len : INTEGER; 
lib_index_ptr : UNSIGNED; 
status : UNSIGNED; 
txtrfa_ptr : RfaPtr; 


(*Name of file to hold 
extracted module*) 

(*Extracted mod put here,*) 

(* then moved to here*) 
(*For loop control*) 

[255] OF CHAR; (*File containing extracted 
module*) 

(*nullstring, pos, and len used to*) 
(*find string in extracted file reed*) 
(*Value returned in library init*) 
(*Return status for function calls*) 
(*For key lookup and insertion*) 


(*-*-*-*-Function Definitions-*-*-*-*) 

(*Function that returns library 
control index used by librarian*) 
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; 

func: UNSIGNED; 
typ: UNSIGNED; 

VAR namblk: ARRAY[1..u:INTEGER] 
OF INTEGER ;= %IMMED 0): 


INTEGER; EXTERN; 

(*Function that creates/opens library*) 

FUNCTION LBR$OPEN (library_index: UNSIGNED; 

fns: [class_s]PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create_options: ARRAY [12..u2:INTEGER] OF INTEGER := 
%IMMED 0; 

dns: [CLASS_S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= %IMMED 0; 

rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
%IMMED 0; 

VAR rnslen: INTEGER := %IMMED 0): 


(continued on next page) 
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Example 9-3 (Cont.) Extracting a Module from a Library Using DEC Pascal 

INTEGER; EXTERN; 

(^Function that finds a key in an index*) 

FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED; 

key_name:[CLASS_S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 

VAR txtrfa: Rfa_Ptr): 

INTEGER; EXTERN; 


(*Function that retrieves records from modules*) 
FUNCTION LBR$GET_RECORD (library_index: UNSIGNED; 

var textline:[CLASS_S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR); 

INTEGER; 

EXTERN; 

(*Function that closes library*) 

FUNCTION LBR$CLOSE (library_index: UNSIGNED): 

INTEGER; EXTERN; 

BEGIN (* *************** DECLARATIONS COMPLETE ************************* 

*************** main program begins here ********************** *) 

(* Get Library Name, Module To Extract, And File To Hold Extracted Module *) 
WRITE('Library Name: '); READLN(Lib_Name); 

WRITE('Module Name: '); READLN(Module_Name); 

WRITE('Extract Into File: '); READLN(Extracted_File); 

status := LBR$INI_CONTROL (lib_index_ptr, O 

lADDRESS(LBR$C_UPDATE), 

IADDRESS(LBR$C_TYP_TXT)); 

IF NOT ODD(status) THEN 

WRITELN('Initialization Failed') 

ELSE 

BEGIN 

status := LBR$OPEN (lib_index_ptr, 

Lib_Name); 

IF NOT ODD(status) THEN 

WRITELN('Open Not Successful') 

ELSE 

BEGIN © 

status := LBR$LOOKUP_KEY (lib_index_ptr, 

Module_Name, 
txtrfa_ptr); 

IF NOT ODD(status) THEN 

WRITELN('Lookup Key Not Successful') 

ELSE 

BEGIN © 

OPEN(Textout,Extracted_File,new); 

REWRITE(Textout) 

END 

END 

END; 

WHILE ODD(status) DO 
BEGIN 

nullstring := ''(0); 

FOR i := 1 TO 255 DO O 

Outtext[i] := nullstring; 
status := LBR$GET_RECORD (lib_index_ptr, 

Outtext); 

IF NOT ODD(status) THEN 

BEGIN @ 

IF status = lADDRESS(RMS$_EOF) THEN 
WRITELN(' RMS end of file') 

END 


(continued on next page) 
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Example 9-3 (Cont.) Extracting a Module from a Library Using DEC Pascal 


ELSE 

BEGIN © 

pos := INDEX(Outtext, nullstring); (*find first null 

in Outtext*) 

len := pos - 1; (*length of Outtext to first null*) 
IF len >= 1 THEN 
BEGIN 

0uttext2 := SUBSTR(Outtext,1,LEN); 

WRITE(Textout,0uttext2) 

END 

END 

END; (*of WHILE*) 

status := LBR$CLOSE(lib_index_ptr); 

IF NOT ODD(status) THEN 

WRITELN('Close Not Successful') 

END. (*of program extractmod*) 


Each item in the following list corresponds to a number highlighted in 

Example 9-3. 

O Call LBR$INI_CONTROL, specif 3 dng that the function to be performed is 
update and that the library type is text. 

© Call LBR$LOOKUP_KEY to find the key that points to the module you want 
to extract. 

0 Open an output file to receive the extracted module. 

O Initialize the variable that is to receive the extracted records to null 
characters. 

@ Call LBR$GET_RECORD to see if there are more records in the file (module). 
A failure indicates that the end of the file has been reached. 

© Write the extracted record data to the output file. This record should consist 
only of the data up to the first null character. 

9.2.4 Deleting a Module 

Example 9-4 illustrates the deletion of library module from a DEC Pascal 

program. The program is summarized in the following steps: 

1. LBR$LOOKUP_KEY—Call LBR$LOOKUP_KEY, and specify the name of the 
module as the second argument. LBR$LOOKUP_KEY returns the REA of the 
module as the third argument; do not alter this value. 

2. LBR$DELETE_KEY—Call LBR$DELETE_KEY to delete the module key. 
Specify the name of the module as the second argument. 

3. LBR$DELETE_DATA—Call LBR$DELETE_DATA to delete the module itself. 
Specify the RFA of the module obtained in step 1 as the second argument. 
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Example 9-4 Deleting a Module from a Library Using DEC Pascai 


PROGRAM deletemod(INPUT,OUTPUT); 

(*This program deletes a module from a library*) 

TYPE 


Rfa_Ptr = ARRAY [0..1] OF INTEGER; (*Data type of RFA of module*) 

VAR 

LBR$C_UPDATE, (*Constants for LBR$INI_CONTROL*) 

LBR$C_TYP_TXT, (*Defined in $LBRDEF macro*) 

LBR$_KEYNOTFND : [EXTERNAL] INTEGER;(*Error code for LBR$LOOKUP_KEY*) 
Lib_Name : VARYING [128] OF CHAR; (*Name of library receiving module*) 
Module_Name : VARYING [31] OF CHAR; (*Name of module to insert*) 
Text_Data_Record : VARYING [255] OF CHAR; (*Record in new module*) 

Textin : FILE OF VARYING [255] OF CHAR; (*File containing new module*) 
lib_index_ptr : UNSIGNED; (*Value returned in library init*) 

status : UNSIGNED; (*Return status for function calls*) 

txtrfa_ptr : Rfa_Ptr; (*For key lookup and insertion*) 

Key_Not_Found : BOOLEAN ;= FALSE; (*True if new mod not already in lib*) 
(*-*-*-*-Function Definitions-*-*-*-*) 

(*Function that returns library 
control index used by librarian*) 

FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; 

func: UNSIGNED; 
typ: UNSIGNED; 

VAR namblk: ARRAY[1..u:INTEGER] 

OF INTEGER := %IMMED 0): 

INTEGER; EXTERN; 

(*Function that creates/opens library*) 
FUNCTION LBR$OPEN (library_index: UNSIGNED; 

fns: [class_s]PACKED ARRAY[1..u:INTEGER] OF CHAR; 
create_options: ARRAY [12..u2:INTEGER] OF INTEGER := 

%IMMED 0; 

dns: [CLASS_S] PACKED ARRAY [13..u3:INTEGER] OF CHAR 
:= %IMMED 0; 

rlfna: ARRAY [14..u4:INTEGER] OF INTEGER := %IMMED 0; 
rns: [CLASS_S] PACKED ARRAY [15..u5:INTEGER] OF CHAR := 
%IMMED 0; 

VAR rnslen: INTEGER := %IMMED 0): 

INTEGER; EXTERN; 

(*Function that finds a key in index*) 

FUNCTION LBR$LOOKUP_KEY (library_index: UNSIGNED; 

key_name:[CLASS_S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR; 

VAR txtrfa: Rfa_Ptr): 

INTEGER; EXTERN; 

(*Function that removes a key from an index*) 
FUNCTION LBR$DELETE_KEY (library_index: UNSIGNED; 

key_name:[CLASS_S] PACKED ARRAY [1..u:INTEGER] OF 
CHAR): 

INTEGER; 

EXTERN; 


(*Function that deletes all the records 
associated with a module*) 

FUNCTION LBR$DELETE_DATA (library_index: UNSIGNED; 

txtrfa: Rfa_Ptr): 

INTEGER; 

EXTERN; 

(*Function that closes library*) 
FUNCTION LBR$CLOSE (library_index: UNSIGNED): 

INTEGER; EXTERN; 


(continued on next page) 
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Example 9-4 (Cont.) Deleting a Module from a Library Using DEC Pascal 

BEGIN (* *************** DECLARATIONS COMPLETE ************************* 

*************** main program begins here ********************** *) 

(* Get Library Name and Module to Delete *) 

WRITE('Library Name: '); READLN(Lib_Name); 

WRITE('Module Name: '); READLN(Module_Name); 

(*Initialize lib for update access*) 
status := LBR$INI_CONTROL (lib_index_ptr, O 

IADDRESS(LBR$C_UPDATE), (*Update access*) 

IADDRESS(LBR$C_TYP_TXT)); (*Text library*) 

IF NOT ODD(status) THEN (*Check error status*) 

WRITELN('Initialization Failed') 

ELSE (*Initialization was successful*) 

BEGIN 

status := LBR$OPEN (lib_index_ptr, (*Open the library*) 

Lib_Name); 

IF NOT ODD(status) THEN (*Check error status*) 

WRITELN('Open Not Successful') 

ELSE (*Open was successful*) 

BEGIN © (*Is module in the library?*) 

status := LBR$LOOKUP_KEY (lib_index_ptr, 

Module_Name, 
txtrfa_ptr); 

IF NOT ODD(status) THEN (*Check status*) 

WRITELN('Lookup Key Not Successful') 

END 

END; 

IF ODD(status) THEN (*Key was found; delete it*) 

BEGIN 

status := LBR$DELETE_KEY (lib_index_ptr, © 

Module_Name); 

IF NOT ODD(status) THEN 

WRITELN('Delete Key Routine Not Successful') 

ELSE (*Delete key was successful*) 

BEGIN (*Now delete module's data records*) 

status := LBR$DELETE_DATA (lib_index_ptr, O 

txtrfa_ptr); 

IF NOT ODD(status) THEN 

WRITELN('Delete Data Routine Not Successful') 

END 

END; 

status := LBR$CLOSE(lib_index_ptr); (*Close the library*) 

IF NOT ODD(status) THEN 

WRITELN('Close Not Successful'); 

END. (*of program deletemod*) 

Each item in the following list corresponds to a number highlighted in 
Example 9—4. 

O Call LBR$INI_CONTROL, specifying that the function to be performed is 
update and the library type is text. 

© Call LBR$LOOKUP_KEY to find the key associated with the module you 
want to delete. 

© Call LBR$DELETE_KEY to delete the key associated with the module you 
want to delete. If more than one key points to the module, you need to call 
LBR$LOOKUP_KEY and LBR$DELETE_KEY for each key. 

O Call LBR$DELETE_DATA to delete the module (the module header and data) 
from the library. 
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9.2.5 Using Multiple Keys and Multiple Indexes 

You can point to the same module with more than one key. The keys can be in 
the primary index (index 1) or alternate indexes (indexes 2 through 10). The 
best method is to reserve the primary index for module names. In system-defined 
object libraries, index 2 contains the global symbols defined by the various 
modules. 

Example 9—5 illustrates the way that keys can be associated with modules. 


Example 9-5 Associating Keys with Modules 

SUBROUTINE ALIAS (INDEX) 

! Catalogs modules by alias 

INTEGER STATUS, ! Return status 

INDEX, ! Library index 

TXTRFA (2) ! RFA of module 

CHARACTER*31 MODNAME, ! Name of module 
ALIASNAME ! Name of alias 
INTEGER M0DNAME_LEN 1 Length of module name 

INTEGER ALIASNAME_LEN ! Length of alias name 
! VMS library procedures 
INTEGER LBR$L00KUP_KEY, 

LBR$SET_INDEX, 

LBR$INSERT_KEY, 

LIB$GET_INPUT, 

LIB$GET_VALUE 
LIB$L0CC 
! Return codes 

EXTERNAL LBR$_KEYN0TFND, ! Key not found 

LBR$_DUPKEY, ! Duplicate key 

RMS$_E0F, ! End of text in module 

D0LIB_N0M0D ! No such module 

! Get module name from /ALIAS on command line 
CALL CLI$GET_VALUE ('ALIAS', MODNAME) 

! Calculate length of module name 
M0DNAME_LEN = LIB$L0CC (' ', MODNAME) - 1 
! Look up module name in library index 
STATUS = LBR$L00KUP_KEY (INDEX, 

MODNAME (1:M0DNAME_LEN), 
TXTRFA) 

END IF 


(continued on next page) 
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Example 9-5 (Cent.) Associating Keys with Modules 

! Insert aliases if module exists 
IF (STATUS) THEN 
! Set to index 2 

STATUS = LBR$SET_INDEX (INDEX, 2) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Get alias name from /ALIAS on command line 
STATUS = CLI$GET_VALUE ('ALIAS', ALIASNAME) 

1 Insert aliases in index 2 until bad return status 
! which indicates end of qualifier values 
DO WHILE (STATUS) 

1 Calculate length of alias name 
ALIASNAME_LEN = LIB$LOCC (' ', ALIASNAME) - 1 
1 Put alias name in index 
STATUS = LBR$INSERT_KEY (INDEX, 

ALIASNAME (1:ALIASNAME_LEN), 

TXTRFA) 

IF ((.NOT. STATUS) .AND. 

(STATUS .NE. %LOC (LBR$_DUPKEY)) THEN 
CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 

1 Get another alias 

STATUS = CLI$GET_VALUE ('ALIAS', ALIASNAME) 

END DO 

! Issue warning if module does not exist 
ELSE IF (STATUS .EQ. %LOC (LBR$_KEYNOTFND)) THEN 
CALL LIB$SIGNAL (DOLIB_NOMOD, 

%VAL (1), 

MODNAME (1:M0DNAME_LEN)) 

ELSE 

CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 

! Exit 
END 

You can look up a module using any of the keys associated w^ith it. The follov^ing 
code fragment checks index 2 for a key if the lookup in the primary index fails: 

STATUS = LBR$SET_INDEX (INDEX, 1) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

STATUS = LBR$LOOKUP_KEY (INDEX, 

MODNAME (1:M0DNAME_LEN), 

TXTRFA) 

IF (STATUS .EQ. %LOC (LBR$_KEYNOTFND)) THEN 
STATUS = LBR$SET_INDEX (INDEX, 2) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

STATUS = LBR$LOOKUP__KEY (INDEX, 

MODNAME (1;M0DNAME_LEN), 

TXTRFA) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 

There are two ways to identify the keys associated with a module: 

• Use the LBR$LOOKUP_KEY routine to look up the module using one of the 
keys 

• Use LBR$SEARCH to search applicable indexes for the keys. LBR$SEARCH 
calls a user-written routine each time it retrieves a key. The routine must be 
an integer function defined as external that returns a success (odd number) 
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or failure (even number) status. LBR$SEARCH stops processing on a return 
status of failure. 

The subroutine in Example 9-6 lists the names of keys in index 2 (the aliases) 
that point to a module identified on the command line by the module’s name in 
the primary index. 

Example 9-6 Listing Keys Associated with a Moduie 


SUBROUTINE SHOWAL (INDEX) 

1 Lists aliases for a module 

INTEGER STATUS, 1 Return status 

INDEX, 1 Library index 

TXTRFA (2) ! RFA for module text 

CHARACTER*31 MODNAME ! Name of module 

INTEGER MODNAME__LEN ! Length of module name 
! VMS library procedures 
INTEGER LBR$LOOKUP_KEY, 

LBR$SEARCH, 

LIB$LOCC 
! Return codes 

EXTERNAL LBR$_KEYNOTFND, ! Key not found 
DOLIB_NOMOD 1 No such module 
! Search routine 
EXTERNAL SEARCH 
INTEGER SEARCH 

! Get module name and calculate length 
CALL CLI$GET_VALUE ('SHOWALIAS', MODNAME) 
MODNAME_LEN = LIB$LOCC (' MODNAME) - 1 
! Look up module in index 1 
STATUS = LBR$LOOKUP_KEY (INDEX, 

MODNAME (1:M0DNAME_LEN), 
TXTRFA) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Search for alias names in index 2 
STATUS = LBR$SEARCH (INDEX, 

2, 

TXTRFA, 

SEARCH) 


END 

INTEGER FUNCTION SEARCH (ALIASNAME, RFA) 

! Function called for each alias name pointing to MODNAME 
! Displays the alias name 

INTEGER STATUS_OK, ! Good return status 

RFA (2) ! RFA of module 

PARAMETER (STATUS_OK =1)1 Odd number 
CHARACTER*!*) ALIASNAME ! Name of module 
! Display module name 
TYPE *, MODNAME 

1 Exit 

SEARCH = STATUS_OK 
END 
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9.2.6 Accessing Module Headers 

You can store user information in the header of each module up to the total size 
of the header specified at library creation time in the CRE$L_UHDMAX option. 
The total size of each header in bytes is the value of MHD$B_USRDAT plus the 
value assigned to the CRE$L_UHDMAX option. The value of MHD$B_USRDAT 
is defined by the macro $MHDDEF; the default value is 16 bytes. 

To put user data into a module header, first locate the module with 
LBR$LOOKUP_KEY; then move the data to the module header by invoking 
LBR$SET_MODULE, specifying the first argument (index value returned by 
LBR$INI_CONTROL), the second argument (REA returned by LBR$LOOKUP_ 
KEY), and the fifth argument (character string containing the user data). 

To read user data from a module header, first locate the module with 
LBR$LOOKUP_KEY; then, retrieve the entire module header by invoking 
LBR$SET_MODULE, specifying the first, second, third (character string to 
receive the contents of the module header), and fourth (length of the module 
header) arguments. The user data starts at the byte offset defined by MHD$B_ 
USRDAT. Convert this value to a character string subscript by adding 1. 

Example 9-7 displays the user data portion of module headers on SYS$OUTPUT 
and applies updates from SYS$INPUT. 

Example 9-7 Displaying the Module Header 


SUBROUTINE MODHEAD (INDEX) 
! Modifies module headers 


INTEGER STATUS, ! 

INDEX, ! 

TXTRFA (2) ! 

CHARACTER*31 MODNAME ! 
INTEGER MODNAME_LEN ! 
CHARACTER*80 HEADER ! 
INTEGER HEADER_LEN ! 
INTEGER USER_START ! 
CHARACTER*64 USERDATA ! 
INTEGER*2 USERDATA_LEN ! 
! VMS library procedures 
INTEGER LBR$LOOKUP_KEY, 
LBR$SET_MODULE, 
LIB$GET_INPUT, 
LIB$PUT_OUTPUT, 
CLI$GET_VALUE, 
LIB$LOCC 


Return status 

Library index 

REA of module 

Name of module 

Length of module name 

Module header 

Length of module header 

Start of user data in header 

User data part of header 

Length of user data 


! Offset to user data — defined in $MHDDEF 
EXTERNAL MHD$B_USRDAT 
! Return codes 


EXTERNAL LBR$_KEYNOTFND, ! Key not found 
DOLIB_NOMOD ! No such module 
! Calculate start of user data in header 
USER_START = %LOC (MHD$B_USRDAT) + 1 
! Get module name from /MODHEAD on command line 
STATUS = CLI$GET_VALUE ('MODHEAD', MODNAME) 


(continued on next page) 
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Example 9-7 (Cent.) Displaying the Module Header 

! Get module headers until bad return status 
! which indicates end of qualifier values 
DO WHILE (STATUS) 

! Calculate length of module name 
MODNAME_LEN = LIB$LOCC (' MODNAME) - 1 
! Look up module name in library index 
STATUS = LBR$LOOKUP_KEY (INDEX, 

MODNAME (1:M0DNAME_LEN), 

TXTRFA) 

! Get header if module exists 
IF (STATUS) THEN 

STATUS = LBR$SET_MODULE (INDEX, 

TXTRFA, 

HEADER, 

HEADER_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Display header and solicit replacement 
STATUS = LIB$PUT_OUTPUT 

('User data for module '//MODNAME (1:MODNAME_LEN)//':') 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

STATUS = LIB$PUT_OUTPUT 
(HEADER (USER_START;HEADER_LEN)) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

STATUS = LIB$PUT_OUTPUT 

('Enter replacement text below or just hit return;') 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

STATUS = LIB$GET_INPUT (USERDATA,, USERDATA_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Replace user data 
IF (USERDATA_LEN .GT. 0) THEN 
STATUS = LBR$SET_MODULE (INDEX, 

TXTRFA,,, 

USERDATA (1;USERDATA_LEN)) 

END IF 


1 Issue warning if module does not exist 
ELSE IF (STATUS .EQ. %LOC (LBR$_KEYNOTFND)) THEN 
CALL LIB$SIGNAL (DOLIB_NOMOD, 

%VAL (1), 

MODNAME (1;MODNAME_LEN)) 

ELSE 

CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 


! Get another module name 

STATUS = CLI$GET_VALUE ('MODHEAD', MODNAME) 
END DO 


! Exit 
END 


9.2.7 Reading Library Headers 

Call LBR$GET_HEADER to obtain general information concerning the library. 
Pass the value returned by LBR$INI_CONTROL as the first argument. 
LBR$GET_HEADER returns the information to the second argument, which 
must be an array of 128 longwords. The LHI$ symbols identify the significant 
longwords of the array by their byte offsets into the array. Convert these values 
to subscripts by dividing by 4 and adding 1. 
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Example 9—8 reads the library header and displays some information from it. 

Example 9-8 Reading Library Headers 


SUBROUTINE TYPEINFO (INDEX) 

! Types the type, major ID, and minor ID 
! of a library to SYS$OUTPUT 


INTEGER STATUS ! 

INDEX, ! 

HEADER (128), ! 

TYPE, ! 

MAJOR_ID, 

MINOR_ID 

CHARACTER*8 MAJOR_ID_TEXT, ! 

MINOR ID TEXT 


Return status 
Library index 

Structure for header information 
Subscripts for header structure 


Display info in character format 


! VMS library procedures 
INTEGER LBR$GET_HEADER, 

LIB$PUT_OUTPUT 

! Offsets for header — defined in $LHIDEF 
EXTERNAL LHI$L_TYPE, 

LHI$L_MAJORID, 

LHI$L_MINORID 

! Library type values — defined in $LBRDEF 
EXTERNAL LBR$C_TYP_OBJ, 

LBR$C_TYP_MLB, 

LBR$C_TyP_HLP, 

LBR$C_TYP_TXT 


! Get header information 

STATUS = LBR$GET_HEADER (INDEX, HEADER) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Calculate subscripts for header structure 
TYPE = %LOC (LHI$L_TYPE) / 4 + 1 
MAJOR_ID = %L0C (LHI$L_MAJORID) / 4 + 1 
MINOR_ID = %LOC (LHI$L_MINORID) / 4 + 1 
! Display library type 

IF (HEADER (TYPE) .EQ. %LOC (LBR$C_TYP_OBJ)) THEN 
STATUS = LIB$PUT_OUTPUT ('Library type: object') 

ELSE IF (HEADER (TYPE) .EQ. %LOC (LBR$C_TYP_MLB)) THEN 
STATUS = LIB$PUT_OUTPUT ('Library type: macro') 

ELSE IF (HEADER (TYPE) .EQ. %LOC (LBR$C_TYP_HLP)) THEN 
STATUS = LIB$PUT_OUTPUT ('Library type: help') 

ELSE IF (HEADER (TYPE) .EQ. %LOC (LBR$C_TYP_TXT)) THEN 
STATUS = LIB$PUT_OUTPUT ('Library type: text') 

ELSE 


STATUS = LIB$PUT_OUTPUT ('Library type: unknown') 
END IF 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Convert and display major ID 
WRITE (UNIT=MAJOR_ID_TEXT, 

FMT='(I)') HEADER (MAJOR_ID) 

STATUS = LIB$PUT_OUTPUT ('Major ID: '//MAJOR_ID_TEXT) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Convert and display minor ID 
WRITE (UNIT=MINOR_ID_TEXT, 

FMT='(I)') HEADER (MINOR_ID) 

STATUS = LIB$PUT_OUTPUT ('Minor ID: '//MINOR_ID_TEXT) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 


(continued on next page) 


LBR-24 


Librarian (LBR) Routines 
9.2 Using the LBR Routines 


Example 9-8 (Cont.) Reading Library Headers 

! Exit 
END 

9.2.8 Displaying Help Text 

You can display text from a help library by invoking calling the LBR$OUTPUT_ 
HELP routine and specifying the output routine, the keywords, and the name of 
the library. You must also specify the input routine if the prompting mode flag is 
set or if the flags argument is omitted. 


_ Note _ 

If you specify subprograms in an argument list, they must be declared as 
external. 


The LIB$PUT_OUTPUT and LIB$GET_INPUT routines can be used to specify 
the output routine and the input routine. (If you use your own routines, 
make sure the argument lists are the same as for LIB$PUT_OUTPUT and 
LIB$GET_INPUT.) Do not call LBR$INI_CONTROL and LBR$OPEN before 
calling LBR$OUTPUT_HELP. 

Example 9-9 solicits keywords from SYS$INPUT and displays the text associated 
with those keywords on SYS$OUTPUT, thus inhibiting the prompting facility. 


Example 9-9 Displaying Text from a Help Library 


PROGRAM GET HELP 


! Prints help text from 
CHARACTER*31 LIBSPEC ! 
CHARACTER*15 KEYWORD ! 
INTEGER*2 LIBSPEC_LEN, ! 

KEYWORD_LEN ! 
INTEGER FLAGS, ! 

STATUS ! 


i help library 
Library name 
Keyword in help library 
Length of name 
Length of keyword 
Help flags 
Return status 


! VMS library procedures 
INTEGER LBR$OUTPUT_HELP, 

LIB$GET_INPUT, 

LIB$PUT_OUTPUT 
EXTERNAL LIB$GET_INPUT, 

LIB$PUT_OUTPUT 
! Error codes 

EXTERNAL RMS$_EOF, ! End-of-file 

LIB$_INPSTRTRU ! Input string truncated 

! Flag values - defined in $HLPDEF 

EXTERNAL HLP$M_PROMPT, 

HLP$M_PROCESS, 

HLP$M_GROUP, 

HLP$M_SYSTEM, 

HLP$M_LIBLIST, 

HLP$M_HELP 


(continued on next page) 
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Example 9-9 (Cent.) Displaying Text from a Help Library 

! Get library name 

STATUS = LIB$GET_INPUT (LIBSPEC, 

'Library: 

LIBSPEC_LEN) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

IF (LIBSPEC_LEN .EQ. 0) THEN 
LIBSPEC = 'HELPLIB' 

LIBSPEC_LEN = 7 
END IF 

! Set flags for no prompting 
FLAGS = %LOC (HLP$_PROCESS) + 

%LOC (HLP$_GROUP) + 

%LOC (HLP$_SYSTEM) 

! Get first l<eyword 

STATUS = LIB$GET_INPUT (KEYWORD, 

'Keyword or CTRL/Z: ', 

KEYWORD_LEN) 

IF ((.NOT. STATUS) .AND. 

(STATUS .NE. %LOC (LIB$_INPSTRTRU)) .AND. 

(STATUS .NE. %LOC (RMS$_EOF))) THEN 
CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 

! Display text until end-of-file 
DO WHILE (STATUS .NE. %LOC (RMS$_EOF)) 

STATUS = LBR$OUTPUT_HELP (LIB$PUT_OUTPUT,, 

KEYWORD (1:KEYWORD_LEN), 
LIBSPEC (1:LIBSPEC_LEN), 

FLAGS, 

LIB$GET_INPUT) 

IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Get another keyword 

STATUS = LIB$GET_INPUT (KEYWORD, 

'Keyword or CTRL/Z: ', 
KEYWORD_LEN) 

IF ((.NOT. STATUS) .AND. 

(STATUS .NE. %LOC (LIB$_INPSTRTRU)) .AND. 

(STATUS .NE. %LOC (RMS$_EOF))) THEN 
CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 
END DO 

! Exit 
END 


9.2.9 Listing and Processing Index Entries 

You can process index entries an entry at a time by invoking LBR$GET_INDEX. 
The fourth argument specifies a match name for the entry or entries in the index 
to be processed: you can include the asterisk and percent characters in the match 
name for generic processing. For example, MOD* means all entries whose names 
begin with MOD; MOD% means all entries whose names are four characters and 
begin with MOD; and the asterisk (*) means all entries. 

The third argument names a user-written routine that is executed once for each 
index entry specified by the fourth argument. The routine must be a function 
declared as external that returns a success (odd number) or failure (even number) 
status. LBR$GET_INDEX processing stops on a return status of failure. Declare 
the first argument passed to the function as a passed-length character argument; 
this argument contains the name of the index entry. Declare the second argument 
as an integer array of two elements. 
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Example 9—10 obtains a match name from the command line and displays the 
names of the matching entries from index 1 (the index containing the names of 
the modules). 


Example 9-10 Displaying Index Entries 

SUBROUTINE LIST (INDEX) 

! Lists modules in the library 

INTEGER STATUS, ! Return status 

INDEX, ! Library index 

CHARACTER*31 MATCHNAME ! Name of module to list 
INTEGER MATCHNAME_LEN ! Length of match name 

! VMS library procedures 
INTEGER address LBR$GET_INDEX, 

LIB$L0CC 
! Match routine 
INTEGER MATCH 
EXTERNAL MATCH 

! Get module name and calculate length 
CALL CLI$GET_VALUE ('LIST', MATCHNAME) 

MATCHNAME_LEN = LIB$L0CC (' ', MATCHNAME) - 1 
! Call routine to display module names 
STATUS = LBR$GET_INDEX (INDEX, 

1, ! Primary index 
MATCH, 

MATCHNAME (1:MATCHNAME_LEN)) 
IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) 

! Exit 
END 

INTEGER FUNCTION MATCH (MODNAME, RFA) 

! Function called for each module matched by MATCHNAME 
! Displays the module name 

INTEGER STATUS_0K, ! Good return status 

RFA (2) ! RFA of module name in index 

PARAMETER (STATUS_0K =1) ! Odd value 
CHARACTER*(*) MODNAME ! Name of module 
! Display the name 

TYPE *, MODNAME ! Display module name 
! Exit 

MATCH = STATUS_0K 
END 


9.3 LBR Routines 

The follov^ing pages describe the individual LBR routines. 
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LBR$CLOSE—Close a Library 

The LBR$CLOSE routine closes an open library. 

Format 

LBR$CLOSE libraryjndex 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library, 
index argument is the address of the longword that contains the index. 

Description 

When you are finished working with a library, you should call LBR$CLOSE to 
close it. Upon successful completion, LBR$CLOSE closes the open library and 
deallocates all of the memory used for processing it. 

Condition Values Returned 

LBR$ JLLCTL Specified library control index not valid. 

LBR$_LIBNOTOPN Specified library not open. 
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LBR$DELETE_DATA—Delete a Module’s Data 

The LBR$DELETE_DATA routine deletes the module header and data associated 
with the specified module. 


Format 


LBR$DELETE_DATA libraryjndex ,txtrfa 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library__ 
index argument is the address of the longword that contains the index. 

txtrfa 

OpenVMS usage vector Jongword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Record’s file address (RFA) of the module header for the module you want to 
delete. The txtrfa argument is the address of the 2-longword array that contains 
the RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_ 
exit KEY or LBR$PUT_RECORD. 


Description 

If you want to delete a library module, you must first call LBR$DELETE_KEY 
to delete any keys that point to it. If no library index keys are pointing at the 
module header, LBR$DELETE_DATA deletes the module header and associated 
data records; otherwise, this routine returns the error LBR$_STILLKEYS. 

Note that other librarian routines may reuse data blocks that contain no data. 
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Condition Values Returned 

LBR$_ILLCTL 

LBR$_INVRFA 

LBR$_LIBNOTOPN 

LBR$_STILLKEYS 


Specified library control index not valid. 
Specified RFA not valid. 

Specified library not open. 

Keys in other indexes still point at the module 
header. Therefore, the specified module was not 
deleted. 
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LBR$DELETE_KEY—Delete a Key 

The LBR$DELETE_KEY routine deletes a key from a library index. 


Format 


LBR$DELETE_KEY library_index ,key_name 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library, 
index argument is the address of a longword containing the index. 

key_name 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Key to be deleted from the library index. For libraries with binary keys, the 
key_name argument is the address of an unsigned longword containing the key 
number. 

For libraries with ASCII keys, the key_name argument is the address of the 
string descriptor pointing to the key with the following argument characteristics. 


Argument Characteristics 

Entry 

OpenVMS Usage 

Char_string 

Type 

Character string 

Access 

Read only 

Mechanism 

By descriptor 
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Description 

If LBR$DELETE_KEY finds the key specified by key_name in the current 
index, it deletes the key. Note that, if you want to delete a library module, you 
should first use LBR$DELETE_KEY to delete any keys that point to it, then use 
LBR$DELETE_DATA to delete the module’s header and associated data. 

You cannot call LBR$DELETE_KEY from within the user-supplied routine 
specified in LBR$SEARCH or LBR$GET_INDEX. 


Condition Values Returned 

LBR$_ILLCTL 

LBR$_KEYNOTFND 

LBR$_LIBNOTOPN 

LBR$_UPDURTRAV 


Specified library control index not valid. 
Specified key not found. 

Specified library not open. 

Specified index update not valid in a user- 
supplied routine specified in LBR$SEARCH 
or LBR$GET_INDEX. 
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LBR$FIND—Look Up a Module by Its RFA 

The LBR$FIND routine sets the current internal read context for the library to 
the library module specified. 


Format 

LBR$FIND libraryjndex ,txtrfa 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 

txtrfa 

OpenVMS usage vector Jongword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

RFA (record’s file address) of the module header for the module you want to 
access. The txtrfa argument is the address of a 2-longword array containing the 
RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_KEY 
or LBR$PUT_RECORD. 


Description 

You use the LBR$FIND routine to access a module that you had accessed earlier 
in your program. For example, if you look up several keys with LBR$LOOKUP_ 
KEY, you can save the RFAs returned by LBR$LOOKUP_KEY and later use 
LBR$FIND to reaccess the modules. Thus, you do not have to look up the module 
header’s key every time you want to access the module. If the specified RFA is 
valid, LBR$FIND initializes internal tables so that you can read the associated 
data. 
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Condition Values Returned 

LBR$_ILLCTL Specified library control index not valid. 

LBR$_INVRFA Specified RFA not valid. 

LBR$_LIBNOTOPN Specified library not open. 
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LBR$FLUSH—Recover Virtual Memory 

The LBR$FLUSH routine writes modified blocks back to the library file and frees 
the virtual memory the blocks had been using. 


Format 

LBR$FLUSH libraryjndex ,block_type 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library, 
index argument is the address of the longword that contains the index. 

blockjype 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 

Extent of the flush operation. The blockjype argument contains the longword 
value that indicates how the flush operation proceeds. If you specify LBR$C_ 
FLUSHDATA, the data blocks are flushed. If you specify LBR$C_FLUSHALL, 
first the data blocks and then the current library index are flushed. 

Each programming language provides an appropriate mechanism for accessing 
these symbols. 


Description 

LBR$FLUSH cannot be called from other librarian routines that reference cache 
addresses or by routines called by librarian routines. 
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Condition Values Returned 

LBR$_NORMAL 

LBR$_BADPARAM 

LBR$_WRITERR 


Operation completed successfully. 

Error. A value passed to the LBR$FLUSH 
routine was either out of range or an illegal 
value. 

Error. An error occurred during the writing of 
the cached update blocks to the library file. 
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LBR$GET_HEADER—Retrieve Library Header Information 

The LBR$GET_HEADER routine returns information from the library’s header to 
the caller. 


Format 

LBR$GET_HEADER libraryjndex ,retary 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library__ 
index argument is the address of the longword that contains the index. 

retary 

OpenVMS usage vector Jongword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Array of 128 longwords that receives the library header. The retary argument is 
the address of the array that contains the header information. The information 
returned in the array is listed in the following table. Each programming language 
provides an appropriate mechanism for accessing this information. 


Offset in 
Longwords 

Symbolic Name 

Contents 

0 

LHI$L_TYPE 

Library type (see LBR$OPEN for 
possible values) 

1 

LHI$L_NINDEX 

Number of indexes 

2 

LHI$L_MAJORID 

Library format major identification 

3 

LHI$L_MINORID 

Library format minor identification 

4 

LHI$T_LBRVER 

ASCIC version of Librarian 

12 

LHI$L_CREDAT 

Creation date/time 

14 

LHI$L_UPDTIM 

Date/time of last update 
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Offset in 

Longwords Symbolic Name Contents 


16 

LHI$L_UPDHIS 

17 

LHI$L_FREEVBN 

18 

LHI$L_FREEBLK 

19 

LHI$B_NEXTRFA 

21 

LHI$L_NEXTVBN 

22 

LHI$L_FREIDXBLK 

23 

LHI$L_FREEIDX 

24 

LHI$L_HIPREAL 

25 

LHI$L_IDXBLKS 

26 

LHI$L_IDXCNT 

27 

LHI$L_MODCNT 

28 

LHI$L_MHDUSZ 

29 

LHI$L_MAXLUHREC 

30 

LHI$L_NUMLUHREC 

31 

LHI$L_LIBSTATUS 

32-128 



VBN of start of update history 
First logically deleted block 
Number of deleted blocks 

Record’s File Address (RFA) of end of 
library 

Next VBN to allocate at end of file 

Number of free preallocated index 
blocks 

Listhead for preallocated index blocks 
VBN of highest preallocated block 
Number of index blocks in use 
Number of index entries (total) 

Number of entries in index 1 (module 
names) 

Number of bytes of additional 
information reserved in module header 

Maximum number of library update 
history records maintained 

Number of library update history 
records in history 

Library status (false if there was an 
error closing the library) 

Reserved by Digital 


Description 

On successful completion, LBR$GET_HEADER places the library header 
information into the array of 128 longwords. 

Note that the offset is the byte offset of the value into the header structure. You 
can convert the offset to a longword subscript by dividing the offset by 4 and 
adding 1 (assuming that subscripts in your programming language begin with 1). 

Condition Values Returned 

LBR$_LIBNOTOPN Specified library not open. 

LBR$_ILLCTL Specified library control index not valid. 
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LBR$GET_HELP—Retrieve Help Text 

The LBR$GET_HELP routine retrieves help text from a help library, displaying 
it on SYS$OUTPUT or calling your routine for each record returned. 


Format 


LBR$GET_HELP libraryjndex [,line_width] [,routine] [,data] [,key_1] 
[,key_2 . . . ,key_10] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 

Ilne_width 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Width of the help text line. The line_width argument is the address of a 
longword containing the width of the listing line. If you do not supply a line 
width or if you specify 0, the line width defaults to 80 characters per line. 

routine 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by reference 

Routine called for each line of text you want output. The routine argument is 
the address of the procedure value for this user-written routine. 

If you do not supply a routine argument, LBR$GET_HELP calls the Run-Time 
Library procedure LIB$PUT_OUTPUT to send the help text lines to the current 
output device (SYS$OUTPUT). However, if you want SYS$OUTPUT for your 
program to be a disk file rather than the terminal, you should supply a routine to 
output the text. 
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The routine you specify is called with an argument list of four longwords: 

1. The first argument is the address of a string descriptor for the output line. 

2. The second argument is the address of an unsigned longword containing flag 
bits that describe the contents of the text being passed. The possible flags are 
as follows: 

HLP$M_NOHLPTXT Specified help text cannot be found. 
HLP$M_KEYNAMLIN Text contains key names of the printed text. 

HLP$M_OTHERINFO Text is part of the information provided on 

additional help available. 

Each programming language provides an appropriate mechanism for 
accessing these flags. Note that, if no flag bit is set, help text is passed. 

3. The third argument is the address stipulated in the data argument specified 
in the call to LBR$GET_HELP (or the address of a 0 constant if the data 
argument is zero or was omitted). 

4. The fourth argument is a longword containing the current key level. 

The routine you specify must return with success or failure status. A failure 
status (low bit = 0) terminates the current call to LBR$GET_HELP. 

data 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Data passed to the routine specified in the routine argument. The data 
argument is the address of data for the routine. The address is passed to the 
routine specified in the routine argument. If you omit this argument or specify 
it as zero, then the argument passed in your routine will be the address of a zero 
constant. 

key_1,key_2, . . . ,key_10 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by descriptor 

Level of the help text to be output. Each key_l,key_2, . . . ,key_10 argument is 
the address of a descriptor pointing to the key for that level. 

If the key_l descriptor is 0 or if it is not present, LBR$GET_HELP assumes 
that the key_l name is HELP, and it ignores all the other keys. For key_2 
through key_10, a descriptor address of 0, or a length of 0, or a string address of 
0 terminates the list. 
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The key argument may contain any of the following special character strings: 


String Meaning 

* Return all level 1 help text in the library. 

KEY . . . Return all help text associated with the specified key and its subkeys 
(valid for level 1 keys only). 

* . . . Return all help text in the library. 


Description 

LBR$GET_HELP returns all help text in the same format as the output returned 
by the DCL command HELP; that is, it indents two spaces for every key level 
of text displayed. (Because of this formatting, you may want to make your help 
messages shorter than 80 characters, so they fit on one line on terminal screens 
with the width set to 80.) If you do not want the help text indented to the 
appropriate help level, you must supply your own routine to change the format. 

Note that most application programs use LBR$OUTPUT_HELP instead of 
LBR$GET_HELP. 

Condition Values Returned 


LBR$_ILLCTL 

LBR$_LIBNOTOPN 

LBR$_NOTHLPLIB 


Specified library control index not valid. 
Specified library not open. 

Specified library not a help library. 
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LBR$GET_HISTORY—Retrieve a Library Update History Record 

The LBR$GET_HISTORY routine returns each library update history record to a 
user-specified action routine. 


Format 

LBR$GET_HISTORY libraryjndex ,action_routine 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library__ 
index argument is the address of the longword that contains the index. 

action_routine 

OpenVMS usage procedure 
type procedure value 

access modify 

mechanism by reference 

User-supplied routine for processing library update history records. The action_ 
routine argument is the address of the procedure value of this user-supplied 
routine. The routine is invoked once for each update history record in the library. 
One argument is passed to the routine, namely, the address of a descriptor 
pointing to a history record. 


Description 

This routine retrieves the library update history records written by the routine 
LBR$PUT_HISTORY. 

Condition Values Returned 

LBR$_NORMAL Normal exit from the routine. 

LBR$_EMPTYHIST History empty. This is an informational code, not 

an error code. 
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LBR$_NOHISTORY 

LBR$_INTRNLERR 


No update history. This is an informational code, 
not an error code. 

Internal librarian routine error occurred. 
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LBR$GET_INDEX—Call a Routine for Selected Index Keys 

The LBR$GET_INDEX routine calls a user-supplied routine for selected keys in 
an index. 


Format 


LBR$GET_INDEX libraryjndex ,index_number ,routine_name [,nnatch_desc] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library__ 
index argument is the address of the longword that contains the index. 

index_number 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Number of the library index. The index_number argument is the address of a 
longword containing the index number. This is the index number associated 
with the keys you want to use as input to the user-supplied routine (see 
Section 9.1.2.3). 

routine_name 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by reference 

User-supplied routine called for each of the specified index keys. The routine^ 
name argument is the address of the procedure value for this user-supplied 
routine. 

LBR$GETJNDEX passes two arguments to the routine: 

• A key name. 

— For libraries with ASCII keys, the key_name argument is the address of 
a string descriptor pointing to the key. Note that the string and the string 
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descriptor passed to the routine are valid only for the duration of that 
call. The string must be privately copied if you need it again for more 
processing. 

- For libraries with binary keys, the key_name argument is the address of 
an unsigned longword containing the key number. 

• The record’s file address (RFA) of the module’s header for this key name. The 
RFA argument is the address of a 2-longword array that contains the RFA. 

The routine must return a value to indicate success or failure. If the routine 
returns a false value (low bit = 0), LBR$GET_INDEX stops searching the index 
and returns the status value of the user-specified routine to the calling program. 

The routine cannot contain calls to either LBR$DELETE_KEY or LBR$INSERT_ 
KEY. 

match_desc 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Key matching identifier. The match_desc argument is the address of a string 
descriptor pointing to a string used to identify which keys result in calls to the 
user-supplied routine. Wildcard characters are allowed in this string. If you omit 
this argument, the routine is called for every key in the index. The match_desc 
argument is valid only for libraries that have ASCII keys. 


Description 

LBR$GET_INDEX searches through the specified index for a key that matches 
the argument match_desc. Each time it finds a match, it calls the routine 
specified by the routine__name argument. If you do not specify the match_desc 
argument, it calls the routine for every key in the index. 

For example, if you call LBR$GET_INDEX with match_desc equal to TR* and 
index_number set to 1 (module name table), then LBR$GET_INDEX calls 
routine_name for each module whose name begins with TR. 


Condition Values Returned 

LBR$_ILLCTL 

LBR$_ILLIDXNUM 

LBR$_LIBNOTOPN 

LBR$_NULIDX 


Specified library control index not valid. 
Specified index number not valid. 
Specified library not open. 

Specified library empty. 


LBR-45 


Librarian (LBR) Routines 
LBR$GET_RECORD 


LBR$GET_RECORD—Read a Data Record 

The LBR$GET_RECORD routine returns the next data record in the module 
associated with a specified key. 


Format 


Returns 


LBR$GET_RECORD libraryjndex [Jnbufdes] [,outbufdes] 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. The 
library must be open and LBR$LOOKUP_KEY or LBR$FIND must have been 
called to find the key associated with the module whose records you want to read. 

inbufdes 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

User buffer to receive the record. The inbufdes argument is the address 
of a string descriptor that points to the buffer that receives the record from 
LBR$GET_RECORD. This argument is required when the librarian subroutine 
record access is set to move mode (which is the default). This argument is not 
used if the record access mode is set to locate mode. The DESCRIPTION section 
contains more information about the locate and move modes. 

outbufdes 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

String descriptor that receives the actual length and address of the data for the 
record returned. The outbufdes argument is the address of the string descriptor 
for the returned record. The length and address fields of the string descriptor are 
filled in by the LBR$GET_RECORD routine. This parameter must be specified 
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when Librarian subroutine record access is set to locate mode. This parameter is 
optional if record access mode is set to move mode. The DESCRIPTION section 
contains more information about the locate and move modes. 


Description 

Before calling LBR$GET_RECORD, you must first call LBR$LOOKUP_ICEY or 
LBR$FIND to set the internal library read context to the record’s file address 
(REA) of the module header of the module whose records you want to read. 

LBR$GET_RECORD uses two record access modes: locate mode and move 
mode. Move mode is the default. The LBR$SET_LOCATE and LBR$SET_MOVE 
subroutines set these modes. The record access modes are mutually exclusive; 
that is, when one is set the other is turned off. If move mode is set, LBR$GET_ 
RECORD copies the record to the user-specified buffer described by inbufdes. If 
you have optionally specified the output buffer string descriptor, outbufdes, the 
librarian fills it with the actual length and address of the data. If locate mode 
is set, LBR$GET_RECORD returns the record by way of an internal subroutine 
buffer, pointing the outbufdes descriptor to the internal buffer. The second 
parameter, inbufdes, is not used when locate mode is set. 


Condition Values Returned 

LBR$_ILLCTL 

LBR$_LIBNOTOPN 

LBR$_LKPNOTDON 

RMS$_EOF 


Specified library control index not valid. 
Specified library not open. 

Requested key lookup not done. 

Error. An attempt has been made to read past 
the logical end of the data in the module. 
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LBR$INI_CONTROL—Initialize a Library Control Structure 

The LBR$INI_CONTROL routine initializes a control structure, called a library 
control index, to identify the library for use by other Librarian routines. 


Format 

LBR$INI_CONTROL libraryjndex ,func [,type] [,namblk] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of a longword that is to receive the index. 

func 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library function to be performed. The func argument is the address of the 
longword that contains the library function. Valid functions are LBR$C_CREATE, 
LBR$C_READ, and LBR$C_UPDATE. Each programming language provides an 
appropriate mechanism for accessing these symbols. 

type 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library type. The type argument is the address of the longword containing the 
library type. Valid library types include the following: 

• LBR$C_TYP_OBJ (VAX object) 

• LBR$C_TYP_SHSTB (VAX shareable image), 

• LBR$C_TYP_EOBJ (AXP object) 

• LBR$C_TYP_ESHSTB (AXP shareable image) 
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• LBR$C_TYP_MLB (macro) 

• LBR$C_TYP_HLP (help), 

• LBR$C_TYP_TXT (text) 

• LBR$C_TYP_UNK (unknown), 

• LBR$C_TYP_NCS (NCS library) 

• For user-developed libraries, a type in the range of LBR$C_TYP_USRLW 
through LBR$C_TYP_USRHL 

nambik 

OpenVMS usage nam 
type longword (unsigned) 

access read only 

mechanism by reference 

OpenVMS RMS name block (NAM). The nambik argument is the address of a 
variable-length data structure containing an RMS NAM block. The LBR$OPEN 
routine fills in the information in the NAM block so that it can be used later to 
open the library. If the NAM block has this file identification in it from previous 
use, the LBR$OPEN routine uses the open-by-NAM block option. This argument 
is optional and should be used if the library will be opened many times during 
a single run of the program. For a detailed description of OpenVMS RMS NAM 
blocks, see the OpenVMS Record Management Services Reference Manual. 


Description 

Except for the LBR$OUTPUT_HELP routine, you must call LBR$INI_CONTROL 
before calling any other librarian routine. After you initialize the library control 
index, you must open the library or create a new one using the LBR$OPEN 
routine. You can then call other librarian routines that you need. After you finish 
working with a library, close it with the LBR$CLOSE routine. 

LBR$INI_CONTROL initializes a library by filling the longword referenced by the 
library_index argument with the control index of the library. Upon completion 
of the call, the index can be used to refer to the current library in all future 
routine calls. Therefore, your program must not alter this value. 

You can have up to 16 libraries open simultaneously in your program. 


Condition Values Returned 

LBR$_NORMAL 

LBR$_ILLFUNC 

LBR$_ILLTYP 

LBR$_TOOMNYLIB 


Library control index initialized successfully. 
Requested function not valid. 

Specified library type not valid. 

Error. An attempt was made to allocate more 
than 16 control indexes. 
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LBR$INSERT_KEY—Insert a New Key 

The LBR$INSERT_KEY routine inserts a new key in the current library index. 


Format 


LBR$INSERT_KEY libraryjndex ,key_name ,txtrfa 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 

key_name 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Name of the new key you are inserting. 

If the library uses binary keys, the key_name argument is the address of an 
unsigned longword containing the value of the key. 

If the library uses ASCII keys, the key_name argument is the address of a string 
descriptor of the key with the following argument characteristics. 


Argument 

Characteristics 

Entry 

OpenVMS Usage 

Char_string 

Type 

Character string 

Access 

Read only 

Mechanism 

By descriptor 
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txtrfa 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access modify 

mechanism by reference 

Record file address (RFA) of the module associated with the new key you are 
inserting. The txtrfa argument is the address of a 2-longword array containing 
the RFA. You can use the RFA returned by the first call to LBR$PUT_RECORD. 


Description 

You cannot call LBR$INSERT_KEY within the user-supplied routine specified in 
LBR$SEARCH or LBR$GET_INDEX. 


Condition Values Returned 

LBR$_ILLCTL 

LBR$_INVRFA 

LBR$_DUPKEY 

LBR$_LIBNOTOPN 

LBR$_UPDURTRAV 


Specified library control index not valid. 
Specified RFA does not point to valid data. 
Index already contains the specified key. 
Specified library not open. 

LBR$INSERT_KEY was called by the user- 
defined routine specified in LBR$SEARCH or 
LBR$GET_INDEX. 
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LBR$LOOKUP_KEY—Look Up a Library Key 

The LBR$LOOKUP_KEY routine looks up a key in the library’s current index 
and prepares to access the data in the module associated with the key. 


Format 

LBR$LOOKUP_KEY libraryjndex ,key_name ,txtrfa 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library^ 
index argument is the address of the longword that contains the index. 

key_name 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Name of the library key. If the library uses binary keys, the key_name argument 
is the address of the unsigned longword value of the key. 

If the library uses ASCII keys, the key_name argument is the address of a string 
descriptor for the key with the following argument characteristics. 


Argument Characteristics 

Entry 

OpenVMS Usage 

Char_string 

Type 

Character string 

Access 

Read only 

Mechanism 

By descriptor 


txtrfa 

OpenVMS usage vector Jongword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 
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The record’s file address (RFA) of the library module header. The txtrfa 
argument is the address of the 2-longword array that receives the RFA of the 
module header. 

Description 

If LBR$LOOKUP_KEY finds the specified key, it initializes internal tables so that 
you can access the associated data. 

This routine returns the RFA (consisting of the virtual block number (VBN) and 
the byte offset) to the 2-longword array referenced by txtrfa. Note that the RFA 
is only 6 bytes long. 

Condition Values Returned 

LBR$_ILLCTL Specified library control index not valid. 

LBR$_INVRFA RFA obtained not valid. 

LBR$_KEYNOTFND Specified key not found. 

LBR$_LIBNOTOPN Specified library not open. 
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LBR$OPEN—Open or Create a Library 

The LBR$OPEN routine opens an existing library or creates a new one. 


Format 


LBR$OPEN libraryjndex [,fns] [,create_options] [,dns] [,rlfna] [,rns] [,rnslen] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library^ 
index argument is the address of a longword containing the index. 

fns 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

File specification of the library. The fns argument is the address of a string 
descriptor pointing to the file specification. Unless the OpenVMS RMS NAM 
block address was previously supplied in the LBR$INI_CONTROL routine and 
contained a file specification, this argument must be included. Otherwise, the 
librarian returns an error (LBR$_NOFILNAM). 

create_options 

OpenVMS usage vector Jongword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library characteristics. The create_options argument is the address of an array 
of 20 longwords that define the characteristics of the library you are creating. If 
you are creating a library with LBR$C_CRFATF, you must include the create- 
options argument. The following table shows the entries that the array must 
contain. Fach programming language provides an appropriate mechanism for 
accessing the listed symbols. 
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Offset in 
Longwords 

Symbolic Name 

Contents 

0 

CRE$L_TYPE 

Library type: 


LBR$C_TYP_UNK (0) 

Unknown/unspecified 


LBR$C_TYP_OBJ (1) 

VAX Object 


LBR$C_TYP_MLB (2) 

Macro 


LBR$C_TYP_HLP (3) 

Help 


LBR$C_TYP_TXT (4) 

Text 


LBR$C_TYP_SHSTB (5) 

VAX Shareable Image 


LBR$C_TYP_NCS (6) 

NCS 


LBR$C_TYP_EOBJ (7) 

Alpha Object 


LBR$C_TYP_ESHSTB (8) 

Alpha Shareable Image 


(9-127) 

Reserved by Digital 


LBR$C_TYP_USRLW (128) 

User library types - low end 
of range 


LBR$C_TYP_USRHI (255) 

User library types - high end 
of range 

1 

CRE$L_KEYLEN 

Maximum length of ASCII 
keys or, if 0, indicates 32-bit 
unsigned keys (binary keys) 

2 

CRE$L_ALLOC 

Initial library file allocation 

3 

CRE$L_IDXMAX 

Number of library indexes 
(maximum of 8) 

4 

CRE$L_UHDMAX 

Number of additional bytes 
to reserve in module header 

5 

CRE$L_ENTALL 

Number of index entries to 
preallocate 

6 

CRE$L_LUHMAX 

Maximum number of library 
update history records to 
maintain 

7 

CRE$L_VERTYP 

Format of library to create: 


CRE$C_VMSV2 

VMS Version 2.0 


CRE$C_VMSV3 

VMS Version 3.0 

8 

CRE$L_IDXOPT 

Index key casing option: 


CRE$C_HLPCASING 

Treat character case as it is 
for help libraries 


CRE$C_OBJCASING 

Treat character case as it is 
for object libraries 


CRE$C_MACTXTCAS 

Treat character case as it is 
for macro and text libraries 

9-19 


Reserved by Digital 


The input of uppercase and lowercase characters is treated differently for help, 
object, macro, and text libraries. For details, see the OpenVMS Command 
Definition, Librarian, and Message Utilities Manual. 
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dns 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Default file specification. The dns argument is the address of the string 
descriptor that points to the default file specification. See the OpenVMS Record 
Management Services Reference Manual for details about how defaults are 
processed. 


rifna 

OpenVMS usage 

type 

access 

mechanism 


longword_unsigned 
longword (unsigned) 
read only 
by reference 


Related file name. The rifna argument is the address of a OpenVMS RMS 
NAM block pointing to the related file name. If you do not specify rifna, no 
related file name processing occurs. If a related file name is specified, only the 
file name, type, and version fields of the NAM block are used for related name 
block processing. The device and directory fields are not used. See the OpenVMS 
Record Management Services Reference Manual for details on processing related 
file names. 


rns 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Resultant file specification returned. The rns argument is the address of a string 
descriptor pointing to a buffer that is to receive the resultant file specification 
string. If an error occurs during an attempt to open the library, the expanded 
name string is returned instead. 

rnslen 

OpenVMS usage longword_signed 
type longword (signed) 

access write only 

mechanism by reference 

Length of the resultant or expanded file name. The rnslen argument is the 
address of a longword receiving the length of the resultant file specification string 
(or the length of the expanded name string if there was an error in opening the 
library). 


Description 

You can call this routine only after you call LBR$INI_CONTROL and before you 
call any other librarian routine except LBR$OUTPUT_HELR 

When the library is successfully opened, the librarian routine reads the library 
header into memory and sets the default index to 1. 

If the library cannot be opened because it is already open for a write operation, 
LBR$OPEN retries the open operation every second for a maximum of 30 seconds 
before returning the OpenVMS RMS error, RMS$_FLK, to the caller. 
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Condition Values Returned 

LBR$_OLDLIBRARY 


LBR$_ERRCLOSE 


LBR$_ILLCREOPT 

LBR$_ILLCTL 

LBR$_ILLFMT 

LBR$_ILLFUNC 

LBR$_LIBOPN 

LBR$_NOFILNAM 

LBR$_OLDMISMCH 

LBR$_TYPMISMCH 


Success. The specified library has been opened; 
the library was created with an old library 
format. 

Error. When the library was last modified while 
opened for write access, the write operation 
was interrupted. This left the library in an 
inconsistent state. 

Requested create options not valid or not 
supplied. 

Specified library control index not valid. 

Specified library format not valid. 

Specified library function not valid. 

Specified library already open. 

Error. The fhs argument was not supplied or the 
OpenVMS RMS NAM block was not filled in. 

Requested library function conflicts with old 
library type specified. 

Library type does not match the requested type. 
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LBR$OUTPUT_HELP—Output Help Messages 

The LBR$OUTPUT_HELP routine outputs help text to a user-supplied output 
routine. The text is obtained from an explicitly named help library or, optionally, 
from user-specified default help libraries. An optional prompting mode is 
available that enables LBR$OUTPUT_HELP to interact with you and continue to 
provide help information after the initial help request has been satisfied. 

Format 

LBR$OUTPUT_HELP output_routine [,output_width] [,line_desc] [,library_name] 

[,flags] [,input_routine] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

output_routine 

OpenVMS usage procedure 
type procedure value 

access write only 

mechanism by reference 

Name of a routine that writes help text a line at a time. The output_routine 
argument is the address of the procedure value of the routine to call. You should 
specify either the address of LIB$PUT_OUTPUT or a routine of your own that 
has the same calling format as LIB$PUT_OUTPUT. 

output_width 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Width of the help-text line to be passed to the user-supplied output routine. The 
output_width argument is the address of a longword containing the width of the 
text line to be passed to the user-supplied output routine. If you omit output^, 
width or specify it as 0, the default output width is 80 characters per line. 

Iine_desc 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Contents of the help request line. The line_desc argument is the address of 
a string descriptor pointing to a character string containing one or more help 
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keys defining the help requested, for example, the HELP command line minus 
the HELP command and HELP command qualifiers. The default is a string 
descriptor for an empty string. 

Iibrary_name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the main library. The library_name argument is the address of a string 
descriptor pointing to the main library file specification string. The default is a 
null string, which means you should use the default help libraries. If you omit 
the device and directory specifications, the default is SYS$HELP. The default file 
type is HLB. 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags specifying help output options. Each programming language provides an 
appropriate mechanism for accessing these flags. The flags argument is the 
address of an unsigned longword that contains the following flags: 


Flag 

Description 

HLP$M_PROMPT 

When set, interactive help prompting is in effect. 

HLP$M_PROCESS 

When set, the process logical name table is searched for 
default help libraries. 

HLP$M_GROUP 

When set, the group logical name table is searched for 
group default help libraries. 

HLP$M_SYSTEM 

When set, the system logical name table is searched for 
system default help libraries. 

HLP$M_LIBLIST 

When set, the list of default libraries available is output 
with the list of topics available. 

HLP$M_HELP 

When set, the list of topics available in a help library is 
preceded by the major portion of the text on HELP. 


If you omit this longword, the default is for prompting and all default library 
searching to be enabled, but no library list will be generated and no help text will 
precede the list of topics. 


input_routine 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by reference 

Routine used for prompting. The input__routine argument is the address of the 
procedure value of the prompting routine. You should specify either the address 
of LIB$GET_INPUT or a routine of your own that has the same calling format as 
LIB$GET_INPUT. This argument must be supplied when the HELP command is 
run in prompting mode (that is, HLP$M_PROMPT is set or defaulted). 
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Description 

The LBR$OUTPUT_HELP routine provides a simple, one-call method to 
initiate an interactive help session. Help library bookkeeping functions, 
such as LBR$INI_CONTROL and LBR$OPEN, are handled internally. You 
should not call LBR$INI_CONTROL or LBR$OPEN before you issue a call to 
LBR$OUTPUT_HELP. 

LBR$OUTPUT_HELP accepts help keys in the same format as LBR$GET_HELP, 
with the following qualifications: 

• If the keyword HELP is supplied, help text on HELP is output, followed by a 
list of HELP subtopics available. 

If no help keys are provided or if the line_desc argument is 0, a list of topics 
available in the root library is output. 

• If the line_desc argument contains a list of help keys, then each key must be 
separated from its predecessor by a slash (/) or by one or more spaces. 

• The first key can specify a library to replace the main library as the root 
library (the first library searched) in which LBR$OUTPUT_HELP searches 
for help. A key used for this purpose must have the form <@filespec>, where 
filespec is subject to the same restrictions as the library__name argument. If 
the specified library is an enabled user-defined default library, then filespec 
can be abbreviated as any unique substring of that default library’s logical 
name translation. 

In default library searches, you can define one or more default libraries for 
LBR$OUTPUT_HELP to search for help information not contained in the root 
library. You do this by equating logical names (HLP$LIBRARY, HLP$LIBRARY_ 
1, . . . ,HLP$LIBRARY_999) to the file specifications of the default help libraries. 
You can define these logical names in the process, group, or system logical name 
table. 

If default library searching is enabled by the flags argument, LBR$OUTPUT_ 
HELP uses those fiags to determine which logical name tables are enabled and 
then automatically searches any user default libraries that have been defined 
in those logical name tables. The library search order proceeds as follows: 
root library, main library (if specified and different from the root library), 
process libraries (if enabled), group libraries (if enabled), system libraries (if 
enabled). If the requested help information is not found in any of these libraries, 
LBR$OUTPUT_HELP returns to the root library and issues a “help not found” 
message. 

To enter an interactive help session (after your initial request for help has been 
satisfied), you must set the HLP$M_PROMPT bit in the flags argument. 

You can encounter four different types of prompt in an interactive help session. 
Each type represents a different level in the hierarchy of help available to you: 

1. If the root library is the main library and you are not currently examining 
HELP for a particular topic, the prompt Topic? is output. 

2. If the root library is a library other than the main library and if you are 
not currently examining HELP for a particular topic, a prompt of the form 
@<library-spec>Topic? is output. 

3. If you are currently examining HELP for a particular topic (and subtopics), a 
prompt of the form <keyword...>suhtopic? is output. 
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4. A combination of 2 and 3. 

When you encounter one of these prompt messages, you can respond in any one 
of several ways. Each type of response and its effect on LBR$OUTPUT_HELP in 
each prompting situation is described in the following table. 


Response Action in the Current Prompt Environment^ 

keyword [ . . . ] (1,2) Search all enabled libraries for these keys. 

(3,4) Search additional help for the current topic 
(and subtopic) for these keys. 

@filespec [keyword[ . . . ]] (1,2) Same as above, except that the root library 

is the library specified by filespec. If the specified 
library does not exist, treat @filespec as a normal 
key. 

(3,4) Same as above; treat @filespec as a normal 
key. 

? (1,2 ) Display a list of topics available in the root 

library. 

(3,4) Display a list of subtopics of the current 
topic (and subtopics) for which help exists. 

Carriage Return (1) Exit from LBR$OUTPUT_HELP. 

(2) Change root library to main library. 

(3,4) Strip the last ke3rword from a list of 
keys defining the current topic (and subtopic) 
environment. 

CTRL/Z (1,2,3,4) Exit from LBR$OUTPUT_HELP. 


^ Keyed to the prompt in the preceding list. 


Condition Values Returned 

LBR$_ILLINROU 

LBR$_ILLOUTROU 

LBR$_NOHLPLIS 

LBR$_TOOMNYARG 

LBR$_USRINPERR 


Input routine improperly specified or omitted. 
Output routine improperly specified or omitted. 
Error. No default help libraries can be opened. 
Error. Too many arguments were specified. 
Error. An error status was returned by the 
user-supplied input routine. 
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LBR$PUT_END—Write an End-of-Module Record 

The LBR$PUT_END routine marks the end of a sequence of records written to a 
library by the LBR$PUT_RECORD routine. 

Format 

LBR$PUT_END libraryjndex 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of a longword containing the index. 

Description 

Call LBR$PUT_END after you write data records to the library with the 
LBR$PUT_RECORD routine. LBR$PUT_END terminates a module by attaching 
a 3-byte logical end-of-file record (hexadecimal 77,00,77) to the data. 

Condition Values Returned 

LBR$_ILLCTL Specified library control index not valid. 

LBR$_LIBNOTOPN Specified library not open. 
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LBR$PUT_HISTORY—Write an Update History Record 

The LBR$PUT_HISTORY routine adds an update history record to the end of the 
update history list. 


Format 

LBR$PUT_HISTORY libraryjndex ,record_desc 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library, 
index argument is the address of the longword that contains the index. 

record_desc 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Library history record. The record_desc argument is the address of a string 
descriptor pointing to the record to be added to the library update history. 


Description 

LBR$PUT_HISTORY writes a new update history record. If the library already 
contains the maximum number of history records (as specified at creation time 
by CRE$L_LUHMAX, see LBR$OPEN for details), the oldest history record is 
deleted before the new record is added. 


Condition Values Returned 

LBR$_NORMAL 

LBR$_NOHISTORY 

LBR$JNTRNLERR 


Normal exit from the routine. 

No update history. This is an informational code, 
not an error code. 

Internal librarian error. 
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LBR$_RECLNG Record length greater than that specified by 

LBR$C_MAXRECSIZ. The record was not 
inserted or truncated. 


LBR-64 



Librarian (LBR) Routines 
LBR$PUT_RECORD 


LBR$PUT_RECORD—Write a Data Record 

The LBR$PUT_RECORD routine writes a data record beginning at the next free 
location in the library. 


Format 

LBR$PUT_RECORD libraryjndex ,bufdes ,txtrfa 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library, 
index argument is the address of the longword that contains the index. 


bufdes 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Record to be written to the library. The bufdes argument is the address of 
a string descriptor pointing to the buffer containing the output record. The 
maximum record size for VAX libraries is symbolically defined as LBR$C_ 
MAXRECSIZ; for AXP libraries, the symbolic maximum record size is ELBR$. 


MAXRECSIZ. 


txtrfa 

OpenVMS usage vectorJongword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Record’s file address (RFA) of the module header. The txtrfa argument is the 
address of a 2-longword array receiving the RFA of the newly created module 
header upon the first call to LBR$PUT_RECORD. 
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Description 

If this is the first call to LBR$PUT_RECORD, this routine first writes a module 
header and returns its RFA to the 2-longword array pointed to by txtrfa. 
LBR$PUT_RECORD then writes the supplied data record to the library. On 
subsequent calls to LBR$PUT_RECORD, this routine writes the data record 
beginning at the next free location in the library (after the previous record). The 
last record written for the module should be followed by a call to LBR$PUT_END. 

Condition Values Returned 

LBR$_ILLCTL Specified library control index not valid. 

LBR$_LIBNOTOPN Specified library not open. 
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LBR$REPLACE_KEY—Replace a Library Key 

The LBR$REPLACE_KEY routine inserts a key in an index by changing the 
pointer associated with an existing key or by inserting a new key. 

Format 

LBR$REPLACE_KEY libraryjndex ,key_name ,oldrfa ,newrfa 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library, 
index argument is the address of the longword that contains the index. 

key_name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Library key (for libraries with ASCII keys). The key_name argument is the 
address of a string descriptor for the key. 

key_name 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library key (for libraries with binary keys). The key_name argument is the 
address of an unsigned longword value for the key. 

oldrfa 

OpenVMS usage vector Jongword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 
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Old RFA. The oldrfa argument is the address of a 2-longword array containing 
the original RFA (returned by LBR$LOOKUP_KEY) of the module header 
associated with the key you are replacing. 

newrfa 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

New RFA. The newrfa argument is the address of a 2-longword array containing 
the RFA (returned by LBR$PUT_RECORD) of the module header associated with 
the new key. 

Description 

If LBR$REPLACE_KEY does not find the key in the current index, it calls the 
LBR$INSERT_KEY routine to insert the key. If LBR$REPLACE_KEY does find 
the key, it modifies the key entry in the index so that it points to the new module 
header. 

Condition Values Returned 

LBR$_ILLCTL Specified library control index not valid. 

LBR$_LIBNOTOPN Specified library not open. 

LBR$_INVRFA Specified RFA not valid. 
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LBR$RET_RMSSTV—Return OpenVMS RMS Status Value 

The LBR$RET_RMSSTV routine returns the status value of the last OPenVMS 
RMS function performed by any librarian subroutine. 


Format 

LBR$RET_RMSSTV 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

None. 


Description 

The LBR$RET_RMSSTV routine returns, as the status value, the status of the 
last OpenVMS RMS operation performed by the librarian. Each programming 
language provides an appropriate mechanism for accessing OpenVMS RMS status 
values. 

Condition Values Returned 

This routine returns any condition values returned by OpenVMS RMS routines. 
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LBR$SEARCH—Search an Index 


The LBR$SEARCH routine finds index keys that point to specified data. 

Format 

LBR$SEARCH libraryjndex ,index_number ,rfa_to_find ,routine_name 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library, 
index argument is the address of the longword that contains the index. 

index_number 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library index number. The index_number argument is the address of 
a longword containing the number of the index you want to search (see 
Section 9.1.2.3). 

rfajojind 

OpenVMS usage vectorJongword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Record’s file address (RFA) of the module whose keys you are searching for. The 
rfa_to_find argument is the address of a 2-longword array containing the RFA 
(returned earlier by LBR$LOOKUP_KEY or LBR$PUT_RECORD) of the module 
header. 

routine_name 

OpenVMS usage 
type 
access 
mechanism 


procedure 
procedure value 
read only 
by reference 


LBR-70 





Librarian (LBR) Routines 
LBRSSEARCH 


Name of a user-supplied routine to process the keys. The routine_name 
argument is the address of the procedure value of a user-supplied routine to call 
for each key entry containing the RFA (in other words, for each key that points to 
the same module header). 

This user-supplied routine cannot contain any calls to LBR$DELETE_KEY or 
LBR$INSERT_KEY. 

Description 

Use LBR$SEARCH to find index keys that point to the same module header. 
Generally, in index number 1 (the module name table), just one key points to 
any particular module; thus, you would probably use this routine only to search 
library indexes where more than one key points to a module. For example, you 
might call LBR$SEARCH to find all the global symbols associated with an object 
module in an object library. 

If LBR$SEARCH finds an index key associated with the specified RFA, it calls a 
user-supplied routine with two arguments: 

• The key argument, which is the address of either of the following: 

- A string descriptor for the keyname (libraries with ASCII keynames). 

- An unsigned longword for the key value (libraries with binary keys). 

• The RFA argument, which is the address of a 2-longword array containing the 
RFA of the module header. 

The routine must return a value to indicate success or failure. If the specified 
routine returns a false value (low bit = 0), then the index search terminates. 

Note that the key found by LBR$SEARCH is valid only during the call to the 
user-supplied routine. If you want to use the key later, you must copy it. 

Condition Values Returned 

LBR$_ILLCTL Specified library control index not valid. 

LBR$_ILLIDXNUM Specified library index number not valid. 

LBR$_KEYNOTFND Librarian did not find any keys with the specified 

RFA. 

LBR$_LIBNOTOPN Specified library not open. 


LBR-71 


Librarian (LBR) Routines 
LBR$SETJNDEX 


LBR$SET_INDEX—Set the Current Index Number 

The LBR$SET_INDEX routine sets the index number to use when processing 
libraries that have more than one index. 


Format 


LBR$SETJNDEX libraryjndex ,index_number 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library__ 
index argument is the address of the longword that contains the index. 

index_number 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Index number you want to establish as the current index number. The library,, 
index is the address of the longword that contains the number of the index you 
want to establish as the current index. (See Section 9.1.2.3) 


Description 

When you call LBR$INI_CONTROL, the librarian sets the current library index 
to 1 (the module name table, unless the library is a user-developed library). If 
you need to process another library index, you must use LBR$SET JNDEX to 
change the current library index. 

Note that macro, help, and text libraries contain only one index; therefore, you 
do not need to call LBR$SETJNDEX. Object libraries contain two indexes. If 
you want to access the global symbol table, you must call the LBR$SETJNDEX 
routine to set the index number. User-developed libraries can contain more than 
one index; therefore, you may need to call LBR$SETJNDEX to set the index 
number. 
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Upon successful completion, LBR$SET_INDEX sets the current library index to 
the requested index number. The librarian routines number indexes starting with 
1 . 

Condition Values Returned 

LBR$_ILLCTL Specified library control index not valid. 

LBR$_ILLIDXNUM Library index number specified not valid. 

LBR$_LIBNOTOPN Specified library not open. 
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LBR$SET_LOCATE—Set Record Access to Locate Mode 

The LBR$SET_LOCATE routine sets the record access of librarian subroutines to 
locate mode. 

Format 

LBR$SET_LOCATE libraryjndex 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library_ 
index argument is the address of the longword that contains the index. 

Description 

Librarian record access may be set to move mode (the default set by LBR$SET_ 
MOVE) or locate mode. The setting affects the operation of the LBR$GET_ 
RECORD routine. 

If move mode is set (the default), LBR$GET_RECORD copies the requested 
record to the specified user buffer. If locate mode is set, the record is not copied. 
Instead, the outbufdes descriptor is set to reference the internal librarian 
subroutine buffer that contains the record. 

Condition Values Returned 

LBR$ JLLCTL Specified library control index not valid. 

LBR$_LIBNOTOPN Specified library not open. 
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LBR$SET_MODULE—Read or Update a Module Header 

The LBR$SET_MODULE routine reads, and optionally updates, the module 
header associated with a given record’s file address (RFA). 


Format 

LBR$SET_MODULE libraryjndex ,rfa [,bufdesc] [,buflen] [,updatedesc] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library^ 
index argument is the address of the longword that contains the index. 

rfa 

OpenVMS usage vector Jongword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Record’s file address (RFA) associated with the module header. The rfa argument 
is the address of a 2-longword array containing the RFA returned by LBR$PUT_ 
RECORD or LBR$LOOKUP_KEY. 

bufdesc 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Buffer that receives the module header. The bufdesc argument is the address 
of a string descriptor pointing to the buffer that receives the module header. 

The buffer must be the size specified by the symbol MHD$B_USRDAT plus the 
value of the CRE$L_UHDMAX create option. The MHD$ and CRE$ symbols 
are defined in the modules $MHDDEF and $CREDEF, which are stored in 
SYS$LIBRARY:STARLET.MLB. 
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buflen 

OpenVMS usage longword_signed 
type longword (signed) 

access write only 

mechanism by reference 

Length of the module header. The buflen argument is the address of a longword 
receiving the length of the returned module header. 

updatedesc 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Additional information to be stored with the module header. The updatedesc 
argument is the address of a string descriptor pointing to additional data that 
the librarian stores with the module header. If you include this argument, the 
librarian updates the module header with the additional information. 


Description 

If you specify bufdesc, the librarian routine returns the module header into 
the buffer. If you specify buflen, the librarian routine also returns the buffer’s 
length. If you specify updatedesc, the routine updates the header information. 

You define the maximum length of the update information (by specifying a value 
for CRE$L_UHDMAX) when you create the library. The librarian zero-fills the 
information if it is less than the maximum length or truncates it if it exceeds the 
maximum length. 

Condition Values Returned 

LBR$_HDRTRUNC 

LBR$ILLCTL 
LBR$_ILLOP 


LBR$_INVRFA 

LBR$_LIBNOTOPN 


Buffer supplied to hold the module header was 
too small. 

Specified library control index not valid. 

Error. The updatedesc argument was supplied 
and the library was a Version 1.0 library or the 
library was opened only for read access. 

Specified RFA does not point to a valid module 
header. 

Specified library not open. 
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LBR$SET_MOVE—Set Record Access to Move Mode 

The LBR$SET_MOVE routine sets the record access of Librarian subroutines to 
move mode. 


Format 


LBR$SET_MOVE libraryjndex 


Returns 


Open VMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Argument 

libraryjndex 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Library control index returned by the LBR$INI_CONTROL routine. The library, 
index argument is the address of the longword that contains the index. 


Description 

Librarian record access may be set to move mode (the default, set by LBR$SET_ 
MOVE) or locate mode. The setting affects the operation of the LBR$GET_ 
RECORD routine. If move mode is set, LBR$GET_RECORD copies the requested 
record to the specified user buffer. For details, see the description of LBR$GET_ 
RECORD. 

Condition Values Returned 

LBR$ JLLCTL Specified library control index not valid. 

LBR$_LIBNOTOPN Specified library not open. 
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The callable interface of the Mail utility (MAIL) lets you send messages to users 
on your system or on any other computer connected to your system with DECnet 
for OpenVMS. This chapter describes how application programs using callable 
MAIL routines can perform the following functions: 

• Create and access mail files 

• Access and manipulate a message or group of messages 

• Create and send messages to a user or group of users 

• Access and manipulate the user profile database 

For information about the DCL interface to the Mail utility, see the OpenVMS 
User's Manual. 

10.1 Messages 

Messages are files that contain information you want to send to other users. 
Messages having 1 or 2 blocks are part of a mail file, while messages having more 
than 2 blocks are external sequential files. 

External files reside in the same directory as the mail file that points to them. 

Structure of a Message 

A message consists of header information and the bodypart. The message 
bodypart consists of text records that contain information you want to send to 
another user. 

Figure 10—1 illustrates the format of a mail message. 

Figure 10-1 Standard Message Format 

From: MYN0DE::USER "The Celestial Navigator" O 

To: N0DE::J_D0E © 

CC: USER © 

Subj: Perseids ... O 


(continued on next page) 
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Figure 10-1 (Cont.) Standard Message Format 

Get ready. Tuesday of this week (August 12th), one @ 
of the most abundant meteor showers of the year will occur. 

The Perseids, also known as the St. Laurence's Tears, stream 
across earth's orbit at 319.3 degrees. Radiant 3h4m +58 degrees. 

Fine for photography with an average magnitude of 2.27. 

There will be some fireballs, fainter white or yellow 
meteors, and brighter green or orange or red ones. About one 
third of the meteors, including all the brightest, leave 
yellowish trains, which may be spectacular, up to 2 
degrees wide and lasting up to 100 seconds. Brighter 
meteors often end in flares or bursts. © 

The parts of a message are as follow^s: 

• Header information 

O From: field specifies the sender and an optional personal name string 
0 To: field specifies the direct addressee, 
o CC: field specifies the carbon copy addressee. 

O Subj: field specifies the topic of the message. 

• Bodypart 

© First line of the bodypart 
© Last line of the bodypart 

External Message Identification Number 

In addition, the file name of an external message uses the follow^ing format: 
MAIL$nnnnnnnnnnnnnnnn.MAI 

^vhere 72 ... 72 is the external message identification number. 

10.2 Folders 

MAIL organizes messages by date and time received and, secondarily, by folder 
name. All messages are associated with a folder name—either default folders or 
user-specified folders. The Mail utility associates mail messages with one of three 
default mail folder names. Table 10-1 describes the three default MAIL folders. 


Table 10-1 Default MAIL Folders 


Folder 

Contents 

NEWMAIL 

MAIL 

WASTEBASKET 

Newly received, unread messages 

Messages that have been read and not deleted 

Messages designated for deletion 


You can also place messages in any user-defined mail folder and file. 
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10.3 Mail Files 

A mail file is an indexed file that contains the following types of data: 

• Header information for all messages 

• Text of short messages 

• Pointers to long messages 

In addition, you can select messages from mail files as well as copy or move 
messages to or from mail files. 

Mail File Format 

The indexed mail file format offers two advantages: use of folders and faster 
access time than sequential access. Indexed mail files use two keys to locate 
messages—a primary key denoting the date and time received and a secondary 
key using the folder name. 

10.4 User Profile Database 

The Mail utility maintains an indexed data file VMSMAIL_PROFILE.DATA 
that serves as a system-wide database of user profile entries. A user profile 
entry is a record that contains data describing a MAIL user’s default processing 
characteristics and whose primary key is the username. Table 10-2 summarizes 
information contained in a user profile entry. 


Table 10-2 User Profile Information 


Field 

Function 

Directory 

Default MAIL subdirectory 

Form 

Default print form 

Forwarding address 

Forwarding address 

Personal name string 

User-specified character string included in the message 
header 

Queue name 

Default print queue name 

Flags 

Automatic purge 

CC: prompt 

Copy self forward 

Copy self reply 

Copy self send 

Purging of the wastebasket folder on exiting 

Carbon copy prompt 

Copy to self when forwarding a message 

Copy to self when replying to a message 

Copy to self when sending a message 


Both the callable interface and the user interface access the user profile database 
to determine default processing characteristics. 

10.5 Mail Utility Processing Contexts 

The Mail utility defines four discrete levels of processing, or contexts for 
manipulating mail files, messages, folders, and the user profile database as 
shown in Table 10—3. 
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Table 10-3 

Levels of Mail Utility Processing 

Context 

Entity 

Mail file 

Mail files and folders 

Message 

Mail files, folders, and messages 

Send 

Messages 

User 

User profile database 


Within each context, your application processes specific entities in certain ways 
using callable MAIL routines as described in the sections that follow. 

Initiating a MAIL Context 

You must explicitly begin and end each MAIL context. Each group of routines 
contains a pair of context-initiating and terminating routines. 

When you begin processing in any context, the Mail utility performs the following 
functions: 

1. Allocates sufficient virtual memory to manage context information 

2. Initializes context variables and internal structures 

Terminating a MAIL Context 

Terminating a MAIL processing context deallocates virtual memory. You must 
explicitly terminate processing in any context by calling a context-terminating 
routine. 

10.5.1 Callable Mail Utility Routines 

There are four types of callable Mail utility routines, each corresponding to the 
context within which they execute. A prefix identifies each functional group— 
MAIL$MAILFILE_, MAIL$MESSAGE_, MAIL$SEND_, and MAIL$USER_ 


Table 10—4 lists Mail utility routines according to context. 


Table 10-4 Callable Mail Utility Routines 


Context Routine 


Mail file MAIL$MAILFILE_BEGIN 

MAIL$MAILFILE_CLOSE 
MAIL$MAILFILE_COMPRESS 
MAIL$MAILFILE_END 
MAIL$MAILFILE_INFO_FILE 
MAIL$MAILFILE_MODIFY 
MAIL$MAILFILE_OPEN 
MAIL$MAILFILE_PURGE_WASTE 


(continued on next page) 
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Table 10-4 (Cent.) Callable Mail Utility Routines 

Context Routine 


Message MAIL$MESSAGE_BEGIN 

MAIL$MESSAGE_COPY 
MAIL$MESSAGE_DELETE 
MAIL$MESSAGE_END 
MAIL$MESSAGE_GET 
MAIL$MESSAGE_INFO 
MAIL$MESSAGE_MODIFY 
MAIL$MESSAGE_SELECT 

Send MAIL$SEND_ABORT 

MAIL$SEND_ADD_ADDRESS 

MAIL$SEND_ADD_ATTRIBUTE 

MAIL$SEND_ADD_BODYPART 

MAIL$SEND_BEGIN 

MAIL$SEND_END 

MAIL$SEND_MESSAGE 

User MAIL$USER_BEGIN 

MAIL$USER_DELETE_INFO 

MAIL$USER_END 

MAIL$USER_GET_INFO 

MAIL$USER_SET_INFO 


10.5.2 Single and Multiple Threads 

Once you have successfully initiated MAIL processing in a context, you have 
created a thread. A thread is a series of calls to MAIL routines that uses the 
same context information. Applications can contain one or more threads. 

Single Threads 

For example, an application that begins mail file processing; opens, compresses, 
and closes a mail file; and ends mail file context processing executes a single 
thread of procedures that reference the same context variable names and pass the 
same context information. 

Multiple Threads 

You can create up to 31 concurrent threads. Applications that contain more than 
one thread must maintain unique context variables for each thread in order to 
pass thread-specific context information. 

The Mail utility returns the condition value MAIL$_NOMORECTX when your 
process attempts to exceed the maximum number of allowable threads. 

10.6 Programming Considerations 

The calling sequence for all MAIL routines consists of a status variable, an entry 
point name, and an argument list. All arguments within the argument list are 
required. All callable MAIL routines use the same arguments in their calling 
sequences as described in the following example: 

STATUS=MAIL$MAILFILE_BEGIN(CONTEXT, IN_ITEM_LIST, 0UT_ITEM_LIST) 

The variable status receives the condition value, and the argument context 
receives the context information. The arguments in_item_list and outjtemJist 
are input and output item lists that contain one or more input or output item 
descriptors. 
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10.6.1 Condition Handling 

At run time, a hardware- or software-related event can occur that determines 
whether or not the application executes successfully. The Mail utility processes 
such an event, or condition in the following ways: 

• Signals the condition value 

• Returns the error code 

You can establish your own condition handler or allow the program to signal the 
default condition handler. 

Returning Condition Values 

You can disable signaling for any call by specifying the item code MAIL$_ 
NOSIGNAL as an item in the input item list. 

10.6.2 Item Lists and Item Descriptors 

Your application passes data to callable MAIL routines and receives data from 
routines through data structures called item lists defined in your program. 

10.6.2.1 structure of an Item Descriptor 

An input or output item list is a data structure that consists of one or more input 
or output item descriptors. 

The following table summarizes the characteristics of item lists: 


Item Descriptor 

Characteristics 

Input 

Each descriptor points to a buffer or file from which MAIL 
reads data. 

Output 

Each descriptor points to a buffer or file to which MAIL writes 
data. 


An item descriptor is a data structure consisting of three longwords as described 
in Figure 10—2. 

Figure 10-2 Item Descriptor 
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Item descriptor fields are described as follows: 


Field 


Function 


Item code 
Buffer length 

Buffer address 
Return length address 


Specifies an action the routine is to perform. 

Specifies the length in bytes of an input or output 
buffer. 

Specifies the address of the input or output buffer. 

Depends on the type of item code specified as 
summarized below. 


Item 

Code 

Use 

Input 

Not used; specify 0. 

Output 

Address of a longword that receives 
the length of the result. 


_ Note _ 

You can specify item descriptors in any order within an item list. 


Item Codes 

The item code defines an action that the routine is to perform. Input and output 
item codes are specified in input and output item descriptors, respectively. 

Boolean input and output item codes request an operation but do not pass data to 
the called routine. For example, the item code MAIL$_USER_SET_CC_PROMPT 
sets the CC prompt flag enabling use of CC: field text. 

For a complete list of input and output item codes, see Tables 10-10 and 10-11. 

10.6.2.2 Null Item Lists 

Both the input and output item list arguments in the MAIL routine calling 
sequence are required. However, there might be situations when you do not want 
to request an operation or no input or output item codes are listed for the routine. 
In such cases, you must pass the value 0 in the function call. 

10.6.2.3 Declaring Item Lists and Item Descriptors 

Depending on the programming language you are using, refer to the appropriate 
language reference manual for more information about declaring data structures 
and creating variables. 

10.6.2.4 Terminating an Item List 

Terminate an item list with a null item descriptor. Assign the value 0 to each 
field in the item descriptor. 
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10.6.3 Action Routines 

Certain callable MAIL routines allow you to specify an action routine. An 
action routine transfers control to a user-written subroutine that performs 
specific tasks. 

The mail file, message, and send contexts permit the use of action routines for 
specific reasons. Table 10—5 summarizes the types of action routines and the 
contexts in which they are used. 


Table 10-5 Types of Action Routines 


Context 

Routine 

Action Routine 

Mail file 

MAIL$MAILFILE_INFO_FILE 

Provides information about 
folder and mail files. 

Message 

MAIL$MESSAGE_COPY 

Copies messages between 
files and folders. 

Send 

MAIL$SEND_MESSAGE 

Success and error results; 
sends a text file to an 
existing address list. 


The preceding table summarizes typical uses of action routines. However, an 
action routine can perform any task you specify. See the Guide to Creating 
OpenVMS Modular Procedures for more information about action routines. 

Mail File and Folder Action Routine Calling Sequence 

The main portion of the application calls the action routine and passes values to 
it using parameters. The calling sequence of a mail file or folder action routine is 
as follows: 

entry-point-name(userdata, foldername) 

The argument userdata is the address of a required longword that contains 
user-specified data, and the argument foldername is the address of a descriptor 
of the foldername. 

Send Action Routine Calling Sequence 

The calling sequence of a send action routine is as follows: 

entry-point-name(username,signal-array,userdata) 

The argument username is the address of a descriptor of the username to which 
the application successfully sent a message; signal-array is the address of a 
signal array containing the success message; userdata is the address of an 
optional longword that contains user-specified data. 

10.7 Managing Mail Files 

Using mail files involves opening and closing both default mail files and user- 
created mail files, displaying folder names, and purging and compressing mail 
files. Table 10—6 summarizes each mail file routine and its function. 
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Table 10-6 Mail File Routines 


Routine 

Description 

MAIL$MAILFILE_BEGIN 

Initiates mail file processing 

MAIL$MAILFILE_CLOSE 

Closes a mail file 

MAIL$MAILFILE_COMPRESS 

Compresses a mail file 

MAIL$MAILFILE_END 

Terminates mail file processing 

MAIL$MAILFILE_INFO_FILE 

Obtains information about the mail file 

MAIL$MAILFILE_MODIFY 

Changes the wastebasket folder name and the 
default mail file name 

MAIL$MAILFILE_OPEN 

Opens a mail file 

MAIL$MAILFILE_PURGE_WASTE 

Purges a mail file 


Mail file context processing involves accessing and manipulating one or more mail 
files. 

Initiating the Mail File Context 

Your application must call MAIL$MAILFILE_BEGIN to perform mail file context 
processing. 

When you call MAIL$MAILFILE_BEGIN successfully and begin processing in the 
mail file context, you have created a thread. You must specify the same context 
variable name in routine calls within the same thread. 

Terminating the Mail File Context 

Terminate processing in the mail file context calling MAIL routines in the 
following order: 

1. Terminate message context processing (if applicable) using MAIL$MESSAGE_ 
END. 

2. Close the currently open mail file using MAIL$MAILFILE_CLOSE. 

3. Terminate mail file context processing using MAIL$MAILFILE_END. 

The following sections describe these actions in more detail. 

10.7.1 Opening and Closing Mail Files 

Before you perform any activities on existing messages, folders, and mail files, 
you must first open a mail file. Whenever you open a mail file, you must do so 
explicitly using MAIL$MAILFILE_OPEN. You can open only one mail file per 
mail file thread. 

Note that each routine references the same context variable. An open mail file 
must be explicitly closed with a call to MAIL$MAILFILE_CLOSE. 

10.7.1.1 Using the Default Specification for Mail Files 

To open a mail file, MAIL must first locate it using either a default or a user- 
specified mail file specification. A mail file specification consists of the following 
components: disk and directory, file name, and file type. 
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If you use the default file specification, the Mail utility locates and opens the 
default mail file using the following information: 


Component 

Source 

User’s disk and directory 

MAIL subdirectory 

Mail file name and type 

Retrieved from the user authorization file (UAF) 

Retrieved from the user profile entry 

MAIL.MAI 


10.7.1.2 Specifying an Alternate Mail File Specification 

You can use the default specication for mail files or specify all or part of an 
alternate mail file specification. 

When to Specify an Alternate Mail File Specification 

The following mail file routines accept alternate mail file specifications when you 
use the item codes MAIL$_MAILFILE_DEFAULT_NAME or MAIL$_MAILFILE_ 
NAME or both: 

• MAIL$MAILFILE_COMPRESS 

• MAIL$MAILFILE_INFO_FILE 

• MAIL$MAILFILE_MODIFY 

• MAIL$MAILFILE_OPEN 

How the Mail Utility Creates an Alternate Mail File Specification 

The Mail utility constructs an alternate mail file specification by using program- 
supplied mail file specifications to modify the default specification for mail files in 
the following order of importance: 

1. Program-supplied file specification (MAIL$_MAILFILE_NAME) 

• Program-supplied disk and directory 

• Program-supplied file name and type 

2. Program-supplied default file specification (MAIL$_MAILFILE_DEFAULT_ 
NAME) 

• Program-supplied disk and directory 

• Program-supplied file name and type 

3. Default specification 

If you are using MAIL$_MAILFILE_DEFAULT_NAME and you specify 0 as the 
buffer size and address, the Mail utility uses the current device and directory. 

The default specification for mail files applies unless overridden by your program- 
supplied mail file specifications. Mail file specifications defined with MAIL$_ 
MAILFILE_NAME override those defined with MAIL$_MAILFILE_DEFAULT_ 
NAME. 

For example, an application can override the default specification 
$DISKO:[USER]MAIL.MAIL by defining an alternate device type $DISK99: 
using MAIL$_MAILFILE_NAME. The result is $DISK99:[USER]MAIL.MAI. The 
application can further modify the specification by defining a different mail file 
MYMAILFILE.MAI using MAIL$_MAILFILE_DEFAULT_NAME. The new mail 
file specification is $DISK99:[USER]MYMAILFILE.MAI. 
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10.7.2 Displaying Folder Names 

As the size of your mail files increases with messages and folders, you might 
want to display your folder names. A user-written folder action routine lets you 
do this. 

In the mail file context, MAIL$MAILFILE_INFO_FILE can be used to invoke 
a folder action routine that displays folder names in a mail file. If you specify 
the item code MAIL$_MAILFILE_FOLDER_ROUTINE, MAIL$MAILFILE_INFO 
passes a descriptor of a folder name to the action routine repeatedly until it 
encounters no more folder names and passes a null descriptor. 

10.7.3 Purging Mail Files Using the Wastebasket Folder 

The Mail utility associates messages designated for deletion with a wastebasket 
folder. Purging mail files of messages in the wastebasket folder that are 
designated for deletion is one way to conserve disk space. You can also use 
the Mail utility to conserve disk space by reclaiming disk space and compressing 
mail files, as described in the sections that follow. 

Note that purging the wastebasket folder removes the messages from the 
wastebasket folder but might not reclaim disk space. 

10.7.3.1 Reclaiming Disk Space 

However, simply deleting the messages does not mean you will automatically 
reclaim the disk space. The Mail utility uses a system-defined threshold of bytes 
designated for deletion to determine when to reclaim disk space. When the total 
number of total bytes designated for deletion exceeds the threshold, the Mail 
utility performs a reclaim operation. 

You can override the deleted bytes threshold and request a reclaim operation 
using MAIL$MAILFILE_PURGE_WASTE with the input item code MAIL$_ 
MAILFILE_RECLAIM. 

10.7.3.2 Compressing Mail Files 

Compressing mail files is a way of conserving disk space. Mail file compression 
provides faster access to the folders and messages within the mail file. When 
you call MAIL$MAILFILE_COMPRESS, MAIL removes unused space within the 
specified mail file. 

10.8 Message Context 

Message context processing involves manipulating existing messages as well as 
creating and deleting folders and mail files. Table 10—7 summarizes routines 
used in the message context. 


Table 10-7 Message Routines 

Routine Description 


MAIL$MESSAGE_BEGIN 

MAIL$MESSAGE_COPY 

MAIL$MESSAGE_DELETE 

MAIL$MESSAGE_END 


Initiates message processing 
Copies messages 
Deletes messages 
Terminates message processing 

(continued on next page) 
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Table 10-7 (Cont.) Message Routines 

Routine Description 


MAIL$MESSAGE_GET 

MAIL$MESSAGE_INFO 

MAIL$MESSAGE_MODIFY 

MAIL$MESSAGE_SELECT 


Retrieves a message 

Obtains information about a specified message 

Identfies a message as replied, new, or marked 

Selects a message or messages from the currently open 
mail file 


Initiating the Message Context 

Message context processing can begin only after a mail file has been opened. Your 
application must explicitly call MAIL$MESSAGE_BEGIN in order to execute 
message context processing. 

The Mail utility passes mail file context information to the message context when 
you call MAIL$MESSAGE_BEGIN with the input item code MAIL$_MESSAGE_ 
FILE_CTX. 

Terminating the Message Context 

To terminate message level processing for a specific thread, you must call 
MAIL$MESSAGE_END to deallocate memory. 

10.8.1 Selecting Messages 

Applications select messages using MAIL$MESSAGE_SELECT to copy and move 
messages between folders as well as to read, modify, or delete messages. You 
must select messages before you can use them. You must specify a folder name 
when you select messages. 

You can select messages based on the following criteria: matching character 
strings, message arrival date and time, and message characteristics. 

Matching Character Strings 

You can select a message or set of messages from a mail file by specifying one or 
more character substrings that you want to match with a character substring in 
the header information of a message or group of messages. You must specify the 
specific bodypart in the message header where the substring is located. 

• From: line 

• To: line 

• CC: line 

• Subject: line 

The Mail utility searches the specified folder for message headers that contain 
the matching character substring. This method of selection is useful when you 
want to select and use messages from or to a particular user that are associated 
with many folder names. 

When you specify more than one character substring, the Mail utility performs a 
logical AND operation to find the messages that contain the correct substring. 
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Message Arrival Date and Time 

You can also select a message or group of messages based on their arrival time, 
that is, when you received them. Applications select messages according to two 
criteria as follows: 

• Messages received before a specified date or time or both. 

• Messages received since a specified date or time or both. 

The Mail utility searches the mail file and selects messages whose primary key 
(date and time) matches the date and time specified in your application. 

Message Characteristics 

You can select messages based on MAIL system fiag values that indicate the 
following message characteristics: 

• New 

• Marked 

• Replied 

For example, you can select unread messages in order to display them or to 
display a message you have marked. 

10.8.2 Reading and Printing Messages 

After a message is selected, an application iteratively retrieves the contents 
of the bodypart record by record. The message can be retrieved using 
MAIL$MESSAGE_GET and can then be stored in a buffer or file. 

Displaying a Message 

To display a message on the terminal screen, you should store the message in a 
buffer and use the host programming language command that directs data to the 
screen. 

Printing a Message 

To print a message on a print queue on your system, you should write the 
message to an external file and use the SYS$SNDJBC system service to manage 
print jobs and define queue characteristics. 

10.8.3 Modifying Messages 

Message modification using MAIL$MESSAGE_MODIFY involves setting fiags 
that identify a message or group of messages as having certain characteristics. 
The following table summarizes bit offsets that modify fiag settings: 


Symbol 

Meaning 

MAIL$V_replied 

Flagged as answered 

MAIL$V_marked 

Flagged for display purposes 


10.8.4 Copying and Moving Messages 

You can copy messages between folders within a mail file or between folders in 
different mail files using MAIL$MESSAGE_COPY. The Mail utility copies the 
message from the source folder to the destination folder leaving the original 
message intact. 
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Similarly, you can move messages between folders within a mail file or between 
folders in different mail files using MAIL$MESSAGE_COPY with the item code 
MAIL$_MESSAGE_DELETE. The Mail utility moves a message by copying the 
message from the source folder and copying the message to the destination folder. 
You must specify a folder name. 

When you move a message to another folder within the same mail file, you are 
changing the message’s secondary key—its folder name. 

10.8.4.1 Creating Folders 

You can create a folder in a specified mail file whenever you attempt to copy 
or move a message to a nonexistent folder. When you create a folder, you are 
assigning a previously nonexistent folder name to a message as its secondary key. 

Your application can include a user-written folder action routine that notifies you 
that the folder does not exist and accepts input to create the folder. 

10.8.4.2 Deleting Folders 

You can delete a folder by moving all of the messages within the source folder 
to another folder in the same mail file or to a folder in another mail file. In this 
case, MAIL associates messages that are moved with a new folder name. 

You can also delete a folder by deleting all of the messages in a folder. MAIL 
associates messages designated for deletion with the wastebasket folder name. 

In either case, the original folder name—the secondary key—no longer exists. 

10.8.4.3 Creating Mail Files 

Similarly, you can create a mail file whenever you attempt to copy or move a 
message to a nonexistent mail file. 

Your application can include a user-written mail file action routine that notifies 
you that the mail file does not exist and accepts input to create the mail file. 

Mail file creation involves creating the mail file and then copying or moving the 
message to the new mail file. If the message is shorter than 3 blocks, the Mail 
utility stores the message in the mail file. Otherwise, the Mail utility places a 
pointer to the message in the newly created mail file. 

10.8.5 Deleting Messages 

To delete a message, you need to know its message identification number. 
Applications can retrieve the message identification number by specifying the 
item code MAIL$_MESSAGE_ID when selecting a message or group of messages 
with MAIL$MESSAGE_SELECT. 

When you delete all messages with the same secondary key (folder name) using 
MAIL$MESSAGE_DELETE and specifying the item code MAIL$_MESSAGE_ID, 
you have deleted the folder. 

10.9 Send Context 

Send context processing involves creating and sending new and existing 
messages. Table 10—8 summarizes send routines. 


MAIL-14 



Mail Utility Routines 
10.9 Send Context 


Table 10-8 Send Routines 

Routine 

Description 

MAIL$SEND_ABORT 

MAIL$SEND_ADD_ADDRESS 

MAIL$SEND_ADD_ATTRIBUTE 

MAIL$SEND_ADD_BODYPART 

MAIL$SEND_BEGIN 

MAIL$SEND_END 

MAIL$SEND_MESSAGE 

Aborts a send operation 

Adds an addressee to the address list 

Constructs the message header 

Constructs the body of the message 

Initiates send processing 

Terminates send processing 

Sends a message 


Initiating the Send Context 

You can invoke the send context directly if you are creating a new message. 
Otherwise, to access an existing message, you must open the mail file that 
contains the message, select the message, and retrieve it. 

Terminating the Send Context 

You must terminate the send context explicitly using MAIL$SEND_END. 

10.9.1 Sending New Messages 

You can send new or existing messages to yourself and other users. 

10.9.1.1 Creating a Message 

You create new messages using send context routines. If you want to create and 
send a new message, you do not need to initiate any other context. As mentioned 
earlier, a message consists of two parts—the message header and the message 
bodypart. 

Constructing a message involves building each part of the message separately 
using the following routines: 

• MAIL$SEND_ADD_ATTRIBUTE 

• MAIL$SEND_ADD_BODYPART 

10.9.1.1.1 Constructing the Message Header Each field of the message header 
is a message attribute. You can specify one or more attributes for inclusion in 
the message header using MAIL$SEND_ADD_ATTRIBUTE. During successive 
calls to MAIL$SEND_ADD_ATTRIBUTE, an application specifies the specific 
message attribute to be constructed. 

If you do not specify the From: or To: fields, MAIL provides this information from 
the address list. 

10.9.1.1.2 Constructing the Body of the Message To construct a message, an 
application must specify a series of calls to MAIL$SEND_ADD_BODYPART to 
build a message from successive text records contained in a buffer or file. 

If the body of the message is located in a file, you can build the bodypart with one 
call to MAIL$SEND_ADD_BODYPART by specifying its file name. 
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10.9.1.2 Creating an Address List 

You must create an address list in order to send a message. The address list 
is a file or buffer of addressees to whom you want to send the message. Each 
entry in the address list is a valid username on your system or on another system 
connected to your system by DECnet for OpenVMS. 

Adding Usernames to the Address List 

Usernames are added one at a time to the address list using one or more calls to 
MAIL$SEND_ADD_ADDRESS. 

Username Types 

There are two types of usernames— direct and carbon copy addressees. Direct 
and carbon copy addressees correspond to usernames in the To: and CC: fields of 
the message header. 

10.9.2 Sending Existing Messages 

Sending an existing message involves many tasks as well as initiating the mail 
file context and message context. The following table summarizes the tasks and 
routines involved in sending an existing message: 


Task 

Routine 

Open a mail file 

MAIL$MAILFILE_OPEN 

Select the message 

MAIL$MESSAGE_SELECT 

Retrieve the message 

MAIL$MESSAGE_GET 

Construct the message 

Construct the message header 
Construct the message bodypart 

MAIL$SEND ADD ATTRIBUTE 
MAIL$SEND_ADD_BODYPART 

Create an address list 

MAIL$SEND_ADD_ADDRESS 

Send the message 

MAIL$SEND_MESSAGE 


10.9.3 Send Action Routines 

Once you have created an address list and constructed a message, you can send 
the message using MAIL$SEND_MESSAGE. Optional success and error action 
routines handle signaled success and error events in a synchronous manner. 

For example, If DECnet for OpenVMS returns messages indicating that it might 
not be possible to complete a send operation to some users in your address list, 
a user-specified send action routine might prompt the sender for permission to 
continue the send operation. 

10.9.3.1 Success Action Routines 

A success action routine performs a task upon successful completion of a send 
operation. 

10.9.3.2 Error Handling Routines 

An error action routine is a user-written error handler that signals error 
conditions during a send operation. 
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10.9.3.3 Aborting a Send Operation 

Under certain circumstances, you might want to terminate a send operation 
in progress using MAIL$SEND_ABORT. In this instance, you can use an 
asynchronous system trap (AST) routine that contains a call to MAIL$SEND_ 
ABORT to abort the send operation whenever the user presses the Ctrl/c key 
sequence. 

10.10 User Profile Context 

The user profile processing context functions as a system management tool 
for customizing the programming and interactive mail environments. It lets 
individual users modify their default processing characteristics. 

The user profile database VMSMAIL_PROFILE.DATA contains information that 
application programs and the Mail utility use for processing in any context. 

Table 10—9 summarizes the user context routines. 


Table 10-9 User Profile Context Routines 


Routine 

Description 

MAIL$USER_BEGIN 

Initiates user profile context 

MAIL$USER_DELETE_INFO 

Deletes a user profile entry 

MAIL$USER_END 

Terminates user profile context 

MAIL$USER_GET_INFO 

Retrieves information about a user from the user 
profile 

MAIL$USER_SET_INFO 

Adds or modifies a user profile entry 


Initiating the User Context 

You can invoke the user context directly. 

Terminating the User Context 

You must terminate the user context with MAIL$USER_END. Terminating the 
user context deallocates virtual memory. 

10.10.1 User Profile Entries 

A user profile entry is a dynamic record. The Mail utility creates a user profile 
entry automatically for the calling process if it does not exist. The callable and 
user interfaces of the Mail utility use the data contained in the user profile entry. 
The user profile consists of fields as described in the sections that follow. 

MAIL Subdirectory 

A MAIL subdirectory is the location—that is, the disk and directory 
specification—of your mail files. When you define a MAIL subdirectory, you are 
creating a subdirectory in which the specified mail file and associated external 
messages are to reside. For example: 

$DISK5:[MAILUSER.COMMON.MAIL] 

The subdirectory [.common.mail] represents the MAIL subdirectory specification 
defined in the user profile entry. This subdirectory contains the mail file (for 
example, MAIL.MAI) and any external messages associated with the mail file. 
The disk and directory specification $DISK5:[MAILUSER] is defined in the user 
authorization file (UAF). 
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Flags 

User profile flags can be set to enable or disable automatic purging of deleted 
mail, automatic self-copy when forwarding, replying, or sending messages, and 
use of the CC prompt. 

Form 

The form field of the user profile entry defines the default print form to be used 
by print batch jobs. The string you specify as the default form must match a valid 
print form in use on your system. 

Forwarding Address 

A forwarding address lets you receive messages to your account on another 
system or to have your messages sent to another user either on your system or 
another system. You must specify valid nodenames and usernames. 

Personal Name 

A personal name is a user-specified character string. For example, a personal 
name might include your entire name and phone number. Any phrase beginning 
with alphabetic characters up to a maximum of 255 alphanumeric characters is 
valid. 

Queue Name 

The queue name field defines the default print queue on your system where your 
print jobs are sent. 

10.10.1.1 Adding Entries to the User Profile Database 

Ordinarily, the Mail utility creates a user profile entry for the calling process 
if one does not already exist. A system management application might create 
entries for other users. When you specify the item code MAIL$_USER_CREATE_ 
IF using MAIL$USER_SET_INFO, the Mail utility creates a user profile entry if 
it does not already exist. 

10.10.1.2 Modifying or Deieting User Profiie Entries 

The calling process can modify, delete, or retrieve its own user profile entry 
without privileges. 

The following table summarizes the privileges required to modify or delete user 
profile entries that do not belong to the calling process: 


Procedure 

Privilege 

Function 

MAIL$USER_SET_INFO 

SYSPRV 

To modify another user’s 
profile entry 

MAIL$USER_GET_INFO 

SYSNAM or SYSPRV 

To retrieve information 
about another user 


10.11 Input Item Codes 

Input item codes direct the called routine to read data from a buffer or file and 
perform a task. Table 10—10 summarizes input item codes. 
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Table 10-10 Input Item Codes 


Item Code 

Function 

Mail File Context 



MAIL$_MAILFILE_DEFAULT_NAME Specifies the location (disk and directory) of the default 

mail file MAIL.MAL 


MAIL$_MAILFILE_FOLDER_ROUTINE 

MAIL$_MAILFILE_FULL_CLOSE 

MAIL$_MAILFILE_NAME 

MAIL$_MAILFILE_RECLAIM 

MAIL$_MAILFILE_USER_DATA 


Displays folder names within a specified mail file. 

Requests that the wastebasket folder be purged and 
that a convert/reclaim operation be performed, if 
necessary. 

Specifies the name of a mail file to be opened. 

Overrides the deleted bytes threshold and and requests 
a reclaim operation. 

Passes a longword of user context data to an action 
routine. 


MAIL$_MAILFILE_WASTEBASKET_NAME Specifies a new name for the wastebasket in a specified 

mail file. 


Message Context 

MAIL$_MESSAGE_AUTO_NEW]V[AIL 

MAIL$_MESSAGE_BACK 

MAIL$_MESSAGE_BEFORE 

MAIL$_MESSAGE_CC_SUBSTRING 

MAIL$_MESSAGE_CONTINUE 

MAIL$_MESSAGE_DEFAULT_NAME 

MAJL$_MESSAGE_DELETE 

MAIL$_MESSAGE_FILE_ACTION 

MAIL$_MESSAGE_FILE_CTX 

MAIL$_MESSAGE_FILENAME 

MAIL$_MESSAGE_FOLDER_ACTION 

MAIL$_MESSAGE_FLAGS 

MAIL$_MESSAGE_FLAGS_MBZ 

MAIL$_MESSAGE_FOLDER 

MAIL$_MESSAGE_FROM_SUBSTRING 


Places newly read messages in the MAIL folder 
automatically. 

Returns the first record of the preceding message. 

Selects a message before a specified date. 

Specifies a character string that must match a node 
or username substring in the CC: field of the specified 
message. 

Returns the next text record of the current message. 

Specifies the default mail file specification. 

Deletes a message in the current folder after the 
message has been copied to a new folder. 

Specifies a user-written routine that is called if a mail 
file is to be created. 

Specifies mail file context received from 
MAIL$MAILFILE_BEGIN. 

Specifies the name of a mail file to which the message 
is to be moved. 

Specifies a user-written routine that is called if a folder 
is to be created. 

Specifies MAIL system flags to use when selecting 
messages. 

Specifies MAIL system flags that must be zero. 

Specifies the name of the target folder for moving 
messages. 

Specifies a character string that must match a node or 
username substring in the From: field of the specified 
message. 

(continued on next page) 
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Table 10-10 (Cont.) Input Item Codes 


Item Code 

Function 

Message Context 

MAIL$_MESSAGE_ID 

Specifies the message identification number of the 
message on which an operation is to be performed. 

MAIL$_MESSAGE_NEXT 

Returns the first record of the message following the 
current message. 

MAIL$_MESSAGE_SINCE 

Selects a message received since a specified date. 

MAIL$_MESSAGE_SUBJ_SUBSTRING 

Specifies a character string that must match a node 
or username substring in the Subject: field of the 
specified message. 

MAIL$_MESSAGE_TO_SUBSTRING 

Specifies a character string that must match a 
substring in the To: field of the specified message. 

MAIL$_MESSAGE_USER_DATA 

Specifies a longword to be passed to the folder and mail 
file action routines. 

Send Context 

MAIL$_SEND_CC_LINE 

Specifies the CC: field text. 

MAIL$_SEND_DEFAULT_NAME 

Specifies the default file specification of a text file to be 
opened. 

MAIL$_SEND_ERROR_ENTRY 

Specifies a user-written routine to process errors that 
occur during a send operation. 

MAIL$_SEND_FID 

Specifies the file identifier. 

MAIL$_SEND_FILENAME 

Specifies the input file specification of a text file to be 
opened. 

MAIL$_SEND_FROM_LINE 

Specifies the From: field text. 

MAIL$ SEND PERS NAME 
MAIL$_SEND_NO_PERS_NAME 

Specifies the personal name string 

Specifies that no personal string be used. 

MAIL$_SEND_RECORD 

Specifies the descriptor of a text record to be added to 
the body of a message. 

MAIL$_SEND_SUBJECT 

Specifies the Subject: field text. 

MAIL$_SEND_SUCCESS_ENTRY 

Specifies a user-written routines to process successfully 
completed events during a send operation. 

MAIL$_SEND_TO_LINE 

Specifies the To: field text. 

MAIL$_SEND_USER_DATA 

Specifies a longword passed to the send action routines. 

MAIL$_SEND_USERNAME 

Adds a specified username to the address list. 

MAIL$_SEND_USERNAME_TYPE 

Specifies the type of username added to the address 
list. 

User Context 

MAIL$_USER_CREATE_IF 

Creates a user profile entry. 

MAIL$_USER_FIRST 

Returns information about the first user in the user 
profile database. 


(continued on next page) 
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Table 10-10 (Cont.) Input Item Codes 


Item Code 

Function 

User Context 

MAIL$_USER_NEXT 

Returns information about the next user in the user 
profile database. 

MAIL$ USER SET AUTO PURGE 
MAIL$_USER_SET_NO_AUTO_PURGE 

Sets the automatic purge flag. 

Clears the automatic purge flag. 

MAIL$ USER SET CC PROMPT 
MAIL$_USER_SET_NO_CC_PROMPT 

Sets the CC prompt flag. 

Clears the CC prompt flag. 

MAILS USER SET COPY FORWARD 
MAIL$_USER_SET_NO_COPY_FORWARD 

Sets the copy self forward flag. 

Clears the copy self forward flag. 

MAILS USER SET COPY REPLY 
MAILS_USER_SET_NO_COPY_REPLY 

Sets the copy self reply flag. 

Clears the copy self reply flag. 

MAILS USER SET COPY SEND 
MAILS_USER_SET_NO_COPY_SEND 

Sets the copy self send flag. 

Clears the copy self send flag. 

MAILS USER SET EDITOR 
MAILS_USER_SET_NO_EDITOR 

Specifies the default editor. 

Clears the default editor field. 

MAILS USER SET FORM 
MAILS_USER_SET_NO_FORM 

Specifies the default print form string. 

Clears the default print form field. 

MAILS USER SET FORWARDING 
MAILS_USER_SET_NO_FORWARDING 

Specifies the forwarding address string. 

Clears the forwarding address field. 

MAILS_USER_SET_NEW_MESSAGES 

Specifles the new messages count. 

MAILS USER SET PERSONAL NAME 
MAIL$_USER_SET_NO_PERSONAL_NAME 

Specifies the personal name string. 

Clears the personal name field. 

MAILS USER SET QUEUE 
MAILS_USER_SET_NO_QUEUE 

Specifles the default print queue name string. 

Clears the default print queue name field. 

MAILS USER SET SUB DIRECTORY 
MAILS_USER_SET_NO_SUB_DIRECTORY 

Specifles a MAIL subdirectory. 

Clears the MAIL subdirectory field. 

MAILS_USER_USERNAME 

Points to the username string to specify the user profile 
entry to be modified. 

10.12 Output Item Codes 


Output item codes direct the called routine to return data to a buffer or file which 
is then available for use by the application. Table 10—11 summarizes output item 
codes. 

Table 10-11 Output Item Codes 


Item Code 

Function 

Mail File Context 

MAILS_MAILFILE_INDEXED 

Determines whether the mail file format is indexed. 

MAILS_MAILFILE_DIRECTORY 

Returns the mail file subdirectory specification to the 
caller. 

MAILS_MAILFILE_RESULTSPEC 

Returns the result mail file specification. 


(continued on next page) 
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Table 10-11 (Cont.) Output Item Codes 


Item Code 

Function 

Mail File Context 



MAIL$_MAILFILE_WASTEBASKET 

MAIL$_MAILFILE_DELETED_BYTES 

MAIL$_MAILFILE_MESSAGES_DELETED 

MAIL$_MAILFILE_DATA_RECLAIM 

MAIL$_MAILFILE_DATA_SCAN 

MAIL$_MAILFILE_INDEX_RECLAIM 

MAIL$_MAILFILE_TOTAL_RECLAIM 


Returns the wastebasket folder name for the specified 
file. 

Returns the number of deleted bytes in a specified mail 
file. 

Returns the number of deleted messages. 

Returns the number of data buckets reclaimed. 

Returns the number of data buckets scanned. 

Returns the number of index buckets reclaimed. 
Returns the total number of bytes reclaimed. 


Message Context 

MAIL$_MESSAGE_BINARY_DATE 

MAIL$_MESSAGE_CC 

MAIL$_MESSAGE_CURRENT_ID 

MAIL$_MESSAGE_DATE 

MAIL$_MESSAGE_EXTID 

MAIL$_MESSAGE_FILE_CREATED 

MAIL$_MESSAGE_FOLDER_CREATED 

MAIL$_MESSAGE_FROM 

MAIL$_MESSAGE_RECORD 

MAIL$_MESSAGE_RECORD_TYPE 

MAIL$_MESSAGE_REPLY_PATH 

MAIL$_MESSAGE_RESULTSPEC 

MAIL$_MESSAGE_RETURN_FLAGS 

MAIL$_MESSAGE_SELECTED 

MAIL$_MESSAGE_SENDER 

MAIL$_MESSAGE_SIZE 

MAIL$_MESSAGE_SUBJECT 

MAIL$_MESSAGE_TO 


Returns the date and time received as a binary value. 

Returns the text in the CC: field of the current 
message. 

Returns the message identification number of the 
current message. 

Returns the message creation date string. 

Returns the external message identification number of 
the current message. 

Returns the value of the mail file created flag. 

Returns the value of the folder created flag. 

Returns the text in the From: field of the current 
messsage. 

Returns a record from the current message. 

Returns the record type. 

Returns the reply path. 

Returns the resultant mail file specification. 

Returns the MAIL system flag value of the current 
message. 

Returns the number of selected messages. 

Returns the name of the sender of the current message. 

Returns the size in records of the current message. 

Returns the text in the Subject: field of the specified 
message. 

Returns the text in the To: field of the specified 
message. 


Send Context 

MAIL$_SEND_COPY_FORWARD Returns the value of the caller’s copy forward flag. 

(continued on next page) 
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Table 10-11 (Cont.) Output Item Codes 


Item Code 

Function 

Send Context 



MAIL$_SEND_COPY_REPLY 

MAIL$_SEND_COPY_SEND 

MAIL$_SEND_RESULTSPEC 

MAIL$_SEND_USER 


Returns the value of the caller’s copy reply flag. 

Returns the value of the caller’s copy send flag. 

Returns the resultant file specification of the file to be 
sent. 

Returns the process owner’s username. 


User Context 

MAIL$_USER_AUTO_PURGE 

MAIL$_USER_CAPTIVE 

MAIL$_USER_CC_PROMPT 

MAIL$_USER_COPY_FORWARD 

MAIL$_USER_COPY_REPLY 

MAIL$_USER_COPY_SEND 

MAIL$_USER_EDITOR 

MAIL$_USER_FORM 

MAIL$_USER_FORWARDING 

MAIL$_USER_FULL_DIRECTORY 

MAIL$_USER_NEW_MESSAGES 

MAIL$_USER_PERSONAL_NAME 

MAIL$_USER_QUEUE 

MAIL$_USER_RETURN_USERNAME 

MAIL$_USER_SUB_DIRECTORY 


Returns the value of the automatic purge mail flag. 
Returns the value of the UAF captive flag. 

Returns the value of the CC prompt flag. 

Returns the value of the copy self forward flag. 
Returns the value of the copy self reply flag. 
Returns the value of the copy self send flag. 

Returns the name of the default editor. 

Returns the default print form string. 

Returns the forwarding address string. 

Returns the complete directory path of the mail file 
subdirectory. 

Returns the new message count. 

Returns the personal name string. 

Returns the default queue name string. 

Returns the username string. 

Returns the subdirectory specification. 


10.13 Examples of Using Mail Utility Routines 

This section provides examples of using the mail routines in various programming 
scenarios including the following: 

• Example 10-1 is a C program that sends a MAIL message to another user. 

• Example 10—2 is a C program that displays a user’s folders and returns how 
many messages are in each folder. 

• Example 10—3 is a C program that displays fields in the user’s MAIL profile. 
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Example 10-1 Sending a File 

/* send_message.c */ 

#include <stdio> 

#include <descrip> 

#include <ssdef> 

#include <maildef> 

#include <nam> 

typedef struct itmlst 

{ 

short buffer_length; 
short item_code; 
long buffer_address; 
long return__length_address; 

} ITMLST; 
int 

send context = 0 


ITMLST 

nulllist[] = { {0,0,0,0} }; 
int 

getline(char *line, int max) 

{ 

if (fgets(line, max, stdin) == NULL) 
return 0; 
else 

return strlen(line); 

} 

int 

main (int argc, char *argv[]) 


{ 

char 

to_user[NAM$C_MAXRSS], 
subject_line[NAM$C_MAXRSS], 
file[NAM$C_MAXRSS], 
resultspec[NAM$C_MAXRSS] 

f 

long resultspeclen; 
int 

status = SS$_N0RMAL, 
file_len = 0, 
subject_line_len = 0, 
to user len = 0 


(continued on next page) 
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Example 10-1 (Cent.) Sending a File 

ITMLST 

address_itmlst[] = { 

{sizeof(to_user), MAIL$_SEND_USERNAME, to_user, &to_user_len}, 

{ 0 , 0 , 0 , 0 }}, 

bodypart_itmlst[] = { 

{sizeof(file), MAIL$_SEND_FILENAME, file, &file_len}, 

{ 0 , 0 , 0 , 0 }}, 

out_bodypart_itmlst[] = { 

{sizeof(resultspec), MAIL$_SEND_RESULTSPEC, resultspec, Sresultspeclen}, 

{ 0 , 0 , 0 , 0 }}, 

attribute_itmlst[] = { 

{sizeof(to_user), MAIL$_SEND__TO_LINE, to_user, &to_user_len}, 

{sizeof (subject__line), MAIL$_SEND__SUBJECT, subject_line, &subject__line_len}, 

{ 0 , 0 , 0 , 0 }} 


status = mail$send_begin(&send_context, &nulllist, &nulllist); 
if (status != SS$_N0RMAL) 
exit(status); 

/* Get the destination and add it to the message */ 
printfC'To: "); 

to_user[getline(to_user, NAM$C_MAXRSS) - 1] = '\0'; 

address_itmlst[0].buffer_length = strlen(to_user); 
address_itmlst[0].buffer_address = to_user; 

status = mail$send_add_address(&send_context, address__itmlst, Snulllist); 
if (status != SS$_N0RMAL) 
return(status); 

/* Get the subject line and add it to the message header */ 
printf("Subject: "); 

subject_line[getline(subject_line, NAM$C_MAXRSS) - 1] = '\0'; 

/* Displayed TO: line */ 

attribute_itmlst[0].buffer_length = strlen(to_user); 
attribute_itmlst[0].buffer_address = to_user; 

/* Subject: line */ 

attribute_itmlst[1].buffer_length = strlen(subject_line); 
attribute_itmlst[1].buffer_address = subject_line; 

status = mail$send_add_attribute(&send_context, attribute_itmlst, &nulllist); 
if (status != SS$_N0RMAL) 
return(status); 

/* Get the file to send and add it to the bodypart of the message */ 
printf("File: "); 

file[getline(file, NAM$C_MAXRSS) - 1] = '\0'; 

bodypart_itmlst[0].buffer_length = strlen(file); 
bodypart_itmlst[0].buffer_address = file; 

status = mail$send_add__bodypart(&send_context, bodypart_itmlst, out_bodypart_itmlst); 
if (status != SS$_NORMAL) 
return(status); 

resultspec[resultspeclen] = '\0'; 

printf("Full file spec actually sent: [%s]\n", resultspec); 


(continued on next page) 


MAIL-25 


Mail Utility Routines 

10.13 Examples of Using Mail Utility Routines 


Example 10-1 (Cent.) Sending a File 

/* Send the message */ 

status = mail$send_message(&send_context, nulllist, nulllist); 
if (status != SS$_N0RMAL) 
return(status); 

/* Done processing witht the SEND context */ 
status = mail$send_end(&send_context, nulllist, nulllist); 
if (status l= SS$_N0RMAL) 
return(status); 

return (status); 

} 


Example 10-2 Displaying Folders 

/* show_folders.c */ 

#include <stdio> 
tinclude <descrip> 

#include <ctype> 

#include <ssdef> 

#include <maildef> 

typedef struct itmlst 

{ 

short buffer_length; 
short item_code; 
long buffer_address; 
long return_length_address; 

} ITMLST; 

struct node 

{ 

struct node *next; /* Next folder name node */ 

char *folder_name; /* Zero terminated folder name */ 

}; 

int 

folder_routine(struct node *list, struct dsc$descriptor *name) 

{ 

if (name“>dsc$w_length) 

{ 

while (list->next) 
list = list->next; 

list->next = malloc(sizeof(struct node)); 
list = list->next; 
list->next = 0; 

list->folder_name = malloc (name->dsc$w__length + 1); 

strncpy(list->folder_name,name->dsc$a_pointer,name->dsc$w__length); 

list->folder_name[name->dsc$w_length] = '\0'; 


} 

return(SS$_N0RMAL); 

} 


(continued on next page) 
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Example 10-2 (Cont.) Displaying Folders 

main (int argc, char *argv[]) 

{ 

struct node list = {0,0}; 
int 

message_context = 0, 
file_context = 0, 
messages_selected = 0, 
total_folders = 0, 
total__messages = 0 

ITMLST 

nulllist[] = {{0,0,0,0}}, 
message__in_itmlst[ ] = { 

{sizeof (f ile_context),MAIL$__MESSAGE_FILE_CTX, &f ile_context, 0}, 

{0,0,0,0}}, 

mailfile_info__itmlst[ ] = { 

{4,MAIL$_MAILFILE_FOLDER_ROUTINE,folder_routine,0}, 

{4 ,MAIL$__MAILFILE_USER_DATA, &list, 0} , 

{0,0,0,0}}, 

message__select_in_itmlst[ ] = { 

{0,MAIL$_MESSAGE_FOLDER,0,0}, 

{0,0,0,0}}, 

message_select_out_itmlst[] = { 

{sizeof(messages_selected),MAIL$_MESSAGE_SELECTED,&messages_selected,0}, 
{0,0,0,0}}; 

if (mail$mailfile_begin(&file_context, nulllist, nulllist) == SS$__N0RMAL) { 
if (mail$mailfile_open(&file_context, nulllist, nulllist) == SS$_N0RMAL) { 
if (mail$mailfile__info__file(&file__context, 
mailfile_info_itmlst, 
nulllist) == SS$_N0RMAL) { 
if (mail$message_begin(&message_context, 
message_in_itmlst, 
nulllist) == SS$_N0RMAL) { 
struct node *tmp = &list; 

while(tmp->next) { 
tmp = tmp->next; 

message_select_in__itmlst[0].buffer_address = tmp->folder_name; 
message_select_in__itmlst[0].buffer_length = strlen(tmp->folder_name); 
if (mail$message_select(&message_context, 
message__select__in_itmlst, 
message_select_out_itmlst) == SS$_N0RMAL) { 
printf("Folder %s has %d messages\n", 
tmp->folder_name, messages_selected); 
total_messages += messages^selected; 
total_folders++; 

} 

} 
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printf("Total of %d messages in %d folders\n",total_messages, total__folders); 

} 

mail$message_end(&message_context, nulllist, nulllist); 

} 

mail$mailfile__close(&file__context, nulllist, nulllist); 

} 

mail$mailfile_end(&file_context, nulllist, nulllist); 

} 

} 


Example 10-3 Displaying User Profiie Information 

/* show_profile.c */ 

tinclude <stdio> 
tinclude <ssdef> 
iinclude <jpidef> 

#include <maildef> 
iinclude <stsdef> 

#include <ctype> 
iinclude <nam> 

struct itmlst 

{ 

short buffer_length; 
short item_code; 
long buffer_address; 
long return_length_address; 

}; 

int 

user context = 0 


struct 

itmlst nulllist[] = { {0,0,0,0} }; 
int 

main (int argc, char *argv[]) 

{ 

int 


userlen = 0, 

/* return length of strings */ 

editor_len = 0, 
form_len = 0, 
forwarding_len = 0, 
full_directory_len = 0, 
personal_name_len = 0, 
queue_len = 0, 

/* Flags */ 

auto_purge = 0, 
cc_prompt = 0, 
copy_forward = 0, 
copy_reply = 0, 
copy_send = 0 


(continued on next page) 
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Example 10-3 (Cent.) Displaying User Profile Information 

char 

user[13 ], 

editor[NAM$C_MAXRSS], 
form[NAM$C_MAXRSS], 
forwarding[NAM$C_MAXRSS], 
full_directory[NAM$C_MAXRSS], 
personal_name[NAM$C_MAXRSS], 
queue[NAM$C_MAXRSS] 


short 

new_messages = 0 


struct itmlst 

jpi_list[] = { 

{sizeof(user) - 1, JPI$_USERNAME, user, &userlen}, 

{0,0,0,0}}, 
user_itmlst[] = { 

{0, MAIL$_USER_USERNAME, 0, 0}, 

{0,0,0,0}}, 
out_itmlst[] = { 

/* Full directory spec */ 

{sizeof(full_directory),MAIL$_USER_FULL_DIRECTORY,full_directory,&full_directory_len}, 
/* New message count */ 

{sizeof(new__messages), MAIL$_USER_NEW_MESSAGES, &new_messages, 0}, 

/* Forwarding field */ 

{sizeof(forwarding), MAIL$_USER_FORWARDING, forwarding, &forwarding_len}, 

/* Personal name field */ 

{sizeof(personal_name), MAIL$_USER_PERSONAL_NAME, personal_name, &personal_name_len}, 
/* Editor field */ 

{sizeof(editor), MAIL$_USER_EDITOR, editor, &editor_len}, 

/* CC prompting flag */ 

{sizeof(cc_prompt), MAIL$_USER_CC_PROMPT, &cc_prompt, 0}, 

/* Copy send flag */ 

{sizeof(copy_send), MAIL$_USER_COPY_SEND, &copy_send, 0}, 

/* Copy reply flag */ 

{sizeof(copy_reply), MAIL$_USER COPY_REPLY, &copy_reply, 0}, 

/* Copy forward flag *7 

{sizeof(copy_forward), MAIL$_USER_COPY_FORWARD, &copy_forward, 0}, 

/* Auto purge flag */ 

{sizeof(auto_purge), MAIL$_USER_AUTO_PURGE, &auto_purge, 0}, 

/* Queue field */ 

{sizeof(queue), MAIL$_USER_QUEUE, queue, &queue_len}, 

/* Form field */ 

{sizeof(form), MAIL$_USER_FORM, form, &form_len}, 

{0,0,0,0}}; 
int 

status = SS$ NORMAL 


/* Get a mail user context */ 
status = MAIL$USER_BEGIN(&user_context, 
Snulllist, 

&nulllist); 

if (status != SS$_NORMAL) 
return(status); 

if (argc > 1) { 

strcpy(user,argv[1]); 

else 

{ 

sys$getjpiw(0,0,0,jpi_list,0,0,0); 
user[userlen] = '\0'; 

}; 


(continued on next page) 
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Example 10-3 (Cent.) Displaying User Profile Information 

while(isspace(user[—userlen])) 
user[userlen] = '\0'; 

user_itmlst[0].buffer_length = strlen(user); 
user_itmlst[0].buffer_address = user; 

status = MAIL$USER_GET_INFO(&user_context, user_itmlst, out_itmlst); 
if (status != SS$_N0RMAL) 
return (status); 

/* Release the mail USER context */ 

status = MAIL$USER_END(&user_context, &nulllist, &nulllist); 
if (status != SS$__N0RMAL) 
return(status); 

/* display the information just gathered */ 

full_directory[full directory_len] = '\0'; 

printf("Your mail file directory is %s.\n", full_directory); 

printf("You have %d new messages.\n", new_messages); 

forwarding[forwarding_len] = '\0'; 
if (strlenjforwarding) == 0) 

printf("You have not set a forwarding address.\n"); 
else 

printf("Your mail is being forwarded to %s.\n", forwarding); 

personal_name[personal_name len] = '\0'; 

printf("Your personal name Is \''%s\"\n", personal_name); 

editor[editor_len] = '\0'; 
if (strlen(form) == 0) 

printf("You have not specified an editor.\n"); 
else 

printf("Your editor is %s\n", editor); 

printf("CC prompting is %s.\n"; (cc_prompt == TRUE) ? "disabled" : "enabled"); 

printf("Automatic copy to yourself on"); 
if (copy_send == TRUE) 
printf(" SEND"); 
if (copy_reply == TRUE) { 
if (copy_send == TRUE) 
printf(","); 
printf(" REPLY"); 

} 

if (copy_forward == TRUE) { 

if ((copy_reply == TRUE) || (copy_send == TRUE)) 
printf(","); 
printf(" FORWARD"); 

} 

if ((copy_reply == FALSE) && (copy_send == FALSE) && (copy_forward == FALSE)) 
printf(" Nothing"); 
printf("\n"); 


printf("Automatic deleted message purge is %s.\n", (auto_purge == TRUE) 


} 


queue[queue_len] = '\0 
if (strlen(form) == 0) 
printf("You have not 
else 

printf("Your default 
form[form_len] = '\0'; 
if (strlen(form) == 0) 
printf("You have not 
else 

printf("Your default 


specified a default queue.\n"); 
print queue is %s.\n", queue); 

specified a default print form.Xn"); 
print form is %s.\n", form); 


"disabled" 


"enabled" 
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10.14 Mail Utility Routines 

The following pages describe the individual Mail utility routines. Input and 
output item list arguments use item descriptor fields structured as shown in the 
following diagram: 



ZK-1705-GE 


Item Descriptor Fields 
buffer length 

For input item lists, this word specifies the length (in bytes) of the buffer that 
supplies the information needed by the routine to process the specified item code. 

For output item lists, this word contains a user-supplied integer specifying the 
length (in bytes) of the buffer in which the routine is to write the information. 

The required length of the buffer depends on the item code specified in the item 
code field of the item descriptor. If the value of buffer length is too small, the 
routine truncates the data. 

item code 

For input item lists, a word containing a user-supplied symbolic code that 
specifies an option for the Mail utility operation. For output item lists, a word 
containing a user-supplied symbolic code specifying the item of information that 
the routine is to return. Each programming language provides an appropriate 
mechanism for defining this information. 

buffer address 

For input item lists, a longword containing the address of the buffer that supplies 
information to the routine. For output item lists, a longword containing the user- 
supplied address of the buffer in which the routine is to write the information. 

return length address 

This field is not used for input item lists. For output item lists, this field contains 
a longword specifying the user-supplied address of a longword in which the 
routine writes the actual length in bytes of the information it returns. 
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MAIL$MAILFILE_BEGIN 


Inititates mail file processing. 


Format 

MAIL$MAILFILE_BEGIN context JnJtemJist ,out_itemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Mail file context information to be passed to other mail file routines. The context 
argument is the address of a longword that contains mail file context information. 

You should specify the value of this argument as 0 in the first of a sequence of 
calls to mail file routines. In the following calls, you should specify the mail file 
context value returned by this routine. 

in_item_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The in__itemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by a longword value of 0 . 

For this routine, there are no input item codes. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out__ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 
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The only output item codes for this routine is the MAIL$_MAILFILE_ 
MAIL_DIRECTORY item code. When you specify MAIL$_MAILFILE_MAIL_ 
DIRECTORY, MAIL$MAILFILE_BEGIN returns the mail directory specification 
to the caller. The buffer address field of the item descriptor points to a buffer 
that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$MAILFILE_BEGIN creates and initiates a mail file context for calls to 
other mail file routines. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 

Any condition value returned by LIB$GET_VM, $GETJPIW, and $GETSYI. 
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MAIL$MAILFILE_CLOSE 


Closes the currently open mail file. 


Format 

MAIL$MAILFILE_CLOSE context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains mail file context information 
returned by MAIL$MAILFILE_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MAILFILE_FULL_CLOSE 

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE specifies that 
MAIL$MAILFILE_CLOSE should purge the wastebasket folder when it closes 
the mail file. If the number of bytes deleted by the purge operation exceeds a 
system-defined threshold, MAIL reclaims the deleted space from the mail file. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

The system-defined threshold is reserved by Digital. 
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outjtemjist 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output item Codes 

MAIL$_MAILFILE_DATA_RECLAIM 

When you specify MAIL$_MAILFILE_DATA_RECLAIM, MAIL$MAILFILE_ 
CLOSE returns the number of data buckets reclaimed during the reclaim 
operation as a longword value. 

MAIL$_MAILFILE_DATA_SCAN 

When you specify MAIL$_MAILFILE_DATA_SCAN, MAIL$MAILFILE_CLOSE 
returns the number of data buckets scanned during the reclaim operation as a 
longword value. 

MAIL$_MAILFILEJNDEX_RECLAIM 

When you specify MAIL$_MAILFILE_INDEX_RECLAIM, MAIL$MAILFILE_ 
CLOSE returns the number of index buckets reclaimed during a reclaim operation 
as a longword value. 

MAIL$_MAILFILE_MESSAGES_DELETED 

When you specify MAIL$_MAILFILE_MESSAGES_DELETED, 
MAIL$MAILFILE_CLOSE returns the number of messages deleted as a longword 
value. 

MAIL$_MAILFILE_TOTAL_RECLAIM 

When you specify MAIL$_MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_ 
CLOSE returns the number of bytes reclaimed during a reclaim operation as a 
longword value. 


Description 

If you specify the input item code MAIL$_MAILFILE_FULL_CLOSE, this 
procedure purges the wastebasket folder automatically before it closes the file. If 
the number of bytes deleted by this procedure exceeds the deleted byte threshold, 
the system performs a convert/reclaim operation on the file. 

Condition Values Returned 


SS$_NORMAL 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

MAIL$_NOFILEOPEN 

SS$_ACCVIO 


Normal successful completion. 

The specified item code is invalid. 
The specified item length is invalid. 
The required item is missing. 

No mail file is open. 

Access violation. 
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MAIL$MAILFILE_COMPRESS 

Compresses a mail file. 


Format 

MAIL$MAILFILE_COMPRESS context JnJtemJist ,out_item_list 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Mail file context information to be passed to various mail file routines. The 
context argument is the address of a longword that contains mail file context 
information returned by MAIL$MAILFILE_BEGIN. 

in_item_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The in_itemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MAILFILE_DEFAULT_NAME 

MAIL$_MAILFILE_DEFAULT_NAME specifies the default file specification 
MAIL should use when opening a mail file. The buffer address field points to a 
character string 0 to 255 characters long that defines the default file specification. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_COMPRESS uses the current default directory as the default 
mail file specification. 


MAIL--36 


Mail Utility Routines 
MAIL$MAILFILE_COMPRESS 


If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_ 
COMPRESS creates the default mail file specification from the following sources: 

• Disk and directory defined in the caller’s user authorization file (UAF) 

• Subdirectory defined in the MAIL user profile 

• Default file type of MAI 

MAIL$_MAILFILE_FULL_CLOSE 

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that the 
wastebasket folder be purged and that convert and reclaim operations be 
performed, if necessary. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

MAIL$_MAILFILE_NAME 

MAIL$_MAILFILE_NAME specifies the name of a mail file to be opened. The 
buffer that the buffer address field points to contains a character string of 0 to 
255 characters. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

If you do not specify MAIL$_MAILFILE_NAME, the default mail file name is 
MAIL. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

MAIL$_MAILFILE_RESULTSPEC 

When you specify MAIL$_MAILFILE_RESULTSPEC, the Mail utility returns the 
resultant mail file specification. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


Description 

If you do not specify an input file, the MAIL$MAILFILE_COMPRESS routine 
compresses the currently open MAIL file. The MAIL$MAILFILE_COMPRESS 
routine signals informational messages concerning the phase of the compression. 
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Condition Values Returned 

SS$_NORMAL Normal successful completion. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

MAIL$_NOTISAM The message file is not an indexed file. 

RMS$_FNF The specified file cannot be found. 

RMS$_SHR The specified file is not shareable. 

SS$_ACCVIO Access violation. 

SS$_IVDEVNAM The specified device name is invalid. 

Any condition value returned by LIB$FIND_IMAGE_SYMBOL, LIB$RENAME 
FILE, $CREATE, $OPEN, $PARSE, and $SEARCH. 
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MAIL$MAILFILE_END 


Terminates mail file processing. 


Format 

MAIL$MAILFILE_END context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains MAILFILE context 
information returned by MAIL$MAILFILE_BEGIN. 

If mail file processing is terminated successfully, the Mail utility sets the value of 
the argument context to 0 . 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MAILFILE_FULL_CLOSE 

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that the 
wastebasket folder be purged and that convert and reclaim operations be 
performed, if necessary. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 
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out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

None. 


Description 

The MAIL$MAILFILE_END routine deallocates the mail file context created by 
MAIL$MAILFILE_BEGIN as well as any dynamic memory allocated by other 
mail file processing routines. 

Condition Values Returned 


SS$_NORMAL 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

SS$_ACCVIO 

Any condition value returned 


Normal successful completion. 

The specified item code is invalid. 
The specified item length is invalid. 
The required item is missing. 
Access violation, 
by LIB$FREE_VM. 
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MAIL$MAILFILEJNFO_FILE 


Obtains information about a specified mail file. 


Format 

MAIL$MAILFILEJNFO_FILE context JnJtemJist ,outJtemJist 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 

Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains mail file context information 
returned by MAIL$MAILFILE_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The in__item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MAILFILE_DEFAULT_NAME 

MAIL$_MAILFILE_DEFAULT_NAME specifies the default mail file specification 
MAIL$MAILFILE_INFO_FILE should use when opening a mail file. The buffer 
address field of the item descriptor points to a character string of 0 to 255 
characters that defines the default mail file specification. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_INFO_FILE uses the current default directory as the default 
mail file specification. 
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If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_ 
INFO_FILE creates the default mail file specification from the following sources: 

• Disk and directory defined in the caller’s user authorization file (UAF) 

• Subdirectory defined in the MAIL user profile 

• Default file type of MAI 

MAIL$_MAILFILE_FOLDER_ROUTINE 

MAIL$_MAILFILE_FOLDER_ROUTINE specifies an entry point longword 
address of a user-written routine that MAIL$MAILFILE_INFO_FILE should use 
to display folder names. MAIL$MAILFILE_INFO_FILE calls the user-written 
routine for each folder in the mail file. 

MAIL$_MAILFILE_NAME 

MAIL$_MAILFILE_NAME specifies the name of the mail file to be opened. The 
buffer address field points to a buffer that contains a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

If you do not specify MAIL$_MAIFILE_NAME, the default mail file name is 
MAIL. 

MAIL$_MAILFILE_USER_DATA 

MAIL$_MAILFILE_USER_DATA specifies a longword that MAIL$MAILFILE_ 
INFO_FILE should pass to the user-defined folder name action routine. 

This item code is valid only when used with the item code MAIL$_MAILFILE_ 
FOLDER_ROUTINE. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

MAIL$_MAILFILE_DELETED_BYTES 

When you specify MAIL$_MAILFILE_DELETED_BYTES, MAIL$MAILFILE_ 
INFO_FILE returns the number of deleted bytes in a specified mail file as 
longword value. 

MAIL$_MAILFILE_RESULTSPEC 

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_INFO_ 
FILE returns the resultant mail file specification. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$_MAILFILE_WASTEBASKET 

When you specify MAIL$_MAILFILE_WASTEBASKET, MAIL$MAILFILE_ 
INFO_FILE returns the name of the wastebasket folder of the specified mail file. 
The buffer address field of the item descriptor points to a buffer that receives a 
character string 0 to 39 characters long. 

Specify a value from 0 to 39 in the buffer length field of the item descriptor. 


Description 

If you do not specify an input file, the MAIL$MAILFILE_INFO_FILE returns 
information about the currently open MAIL file. 

Folder Action Routines 

If you use the item code MAIL$_MAILFILE_FOLDER_ROUTINE to specify a 
folder name routine, MAIL$MAILFILE_INFO_FILE passes control to a user- 
specified routine. For example, the folder action routine could display folder 
names. The user routine must return a 32-bit integer code. If the return code 
indicates success, the interactivity between the user’s routine and the callable 
routine can continue. 

The folder action routine passes a pointer to the descriptor of a folder name 
as well as the user data longword. A descriptor of zero length indicates that 
the MAIL$MAILFILE_INFO_FILE routine has displayed all folder names. 

If you do not specify the item code MAIL$_MAILFILE_FOLDER_ROUTINE, 
MAIL$MAILFILE_INFO_FILE does not call any folder action routines. 

Condition Values Returned 


MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

MAIL$_NOFILEOPEN 

MAIL$_NOTISAM 

MAIL$_OPENIN 

SS$_ACCVIO 


The specified item code is invalid. 

The specified item length is invalid. 
The required item is missing. 

The mail file is not open. 

The message file is not an indexed file. 
MAIL cannot open the file as input. 
Access violation. 


Any condition value returned by $CLOSE, $OPEN, $PARSE, and $SEARCH. 
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MAIL$MAILFILE_MODIFY 


Modifies the informational record of an indexed mail file, including the mail file 
name, the default mail file name, and the wastebasket name. 

Format 

MAIL$MAILFILE_MODIFY context JnJtemJist ,outJtemJist 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Mail File context information to be passed to mail file routines. The context 
argument is the address of a longword that contains mail file context information 
returned by MAIL$MAILFILE_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MAILFILE_DEFAULT_NAME 

MAIL$_MAILFILE_DEFAULT_NAME specifies the default file specification 
MAIL should use when opening a mail file. The buffer address field points to 
a buffer that contains a character string of 0 to 255 characters that defines the 
default mail file specification. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_MODIFY uses the current default directory as the default 
mail file specification. 
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If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_ 
MODIFY creates the default mail file specification from the following sources: 

• Disk and directory defined in the caller’s user authorization file (UAF) 

• Subdirectory defined in the MAIL user profile 

• Default file type of MAI 

MAIL$_MAILFILE_NAME 

MAIL$_MAILFILE_NAME specifies the name of the mail file that the Mail 
utility should open. The buffer address field points to a buffer that contains a 
character string of 0 to 255 characters. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

If you do not specify MAIL$_MAILFILE_NAME, the default mail file name is 
MAIL. 

MAIL$_MAILFILE_WASTEBASKET_NAME 

MAILFILE_WASTEBASKET_NAME specifies a new folder name for the 
wastebasket in the specified mail file. The buffer address field points to a 
buffer that contains a character string of 1 to 39 characters. 

outjtemjist 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

MAIL$_MAILFILE_RESULTSPEC 

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL returns the resultant 
mail file specification. The buffer address field points to a buffer that receives a 
character string from 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


Description 

If a mail file is not specified, the currently open mail file is used. 


Condition Values Returned 

MAIL$_ILLFOLNAM 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

MAIL$_NOTISAM 


The specified folder name is illegal. 
The specified item code is invalid. 

The specified item length is invalid. 
The required item is missing. 

The message file is not an indexed file 
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MAIL$_OPENIN MAIL cannot open the file as input. 

SS$_ACCVIO Access violation. 

Any condition value returned by $CLOSE, $FIND, $PUT, and $UPDATE. 
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MAIL$MAILFILE_OPEN 


Opens a specified mail file for processing. You must use this routine to open a 
mail file before you can do either of the following: 

• Call any mail file routines to manipulate mail files 

• Call message routines to read messages from the specified mail file 


Format 

MAIL$MAILFILE_OPEN context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Mail file context information to be passed to mail file routines. The context 
argument is the address of a longword that contains mail file context information 
returned by MAIL$MAILFILE_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MAILFILE_DEFAULT_NAME 

MAIL$_MAILFILE_DEFAULT_NAME specifies the default file specification 
MAIL$MAILFILE_OPEN should use when opening a mail file. The buffer 
address field points to a character string of 0 to 255 characters that defines the 
default file specification. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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If you specify the value 0 in buffer length field of the item descriptor, 
MAIL$MAILFILE_OPEN uses the current default directory as the default 
mail file specification. 

If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_ 
OPEN creates the default mail file specification from the following sources: 

• Disk and directory defined in the caller’s user authorization file (UAF) 

• Subdirectory defined in the MAIL user profile 

• Default file type of MAI 

MAIL$_MAILFILE_NAME 

MAIL$_MAILFILE_NAME specifies the name of the mail file MAIL$MAILFILE_ 
OPEN should open. The buffer address field points to a buffer that contains a 
character string of 0 to 255 characters. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

If you do not MAIL$_MAILFILE_NAME, the default mail file name is MAIL. 

out_ltem_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

MAIL$_MAILFILE_DELETED_BYTES 

When you specify MAIL$_MAILFILE_DELETED_BYTES, MAIL$MAILFILE_ 
OPEN returns the number of deleted bytes in the specified mail file as a longword 
value. 

MAIL$_MAILFILEJNDEXED 

When you specify MAIL$_MAILFILE_INDEXED, MAIL$MAILFILE_OPEN 
returns a Boolean TRUE when you open an indexed file. The buffer length field 
points to a longword that receives the Boolean value. 

MAIL$_MAILFILE_RESULTSPEC 

When you specify MAIL$_MAILFILE_RESULTSPEC, MAIL$MAILFILE_OPEN 
returns the resultant mail file specification. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MAILFILE_WASTEBASKET 

When you specify MAIL$_MAILFILE_WASTEBASKET, MAIL$MAILFILE_OPEN 
returns the name of the wastebasket for the specified mail file. The buffer 
address field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


MAIL-48 



Mail Utility Routines 
MAIL$MAILFILE_OPEN 


Description 

The default mail file specification is MAIL.MAI in the mail subdirectory. 

Condition Values Returned 


MAIL$_FILEOPEN 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

MAIL$_NOMSGS 

SS$_ACCVIO 

Any condition value returned 


The mail file is already open. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

No messages are available. 

Access violation. 

by LIB$GET_VM and $CONNECT, and $OPEN. 
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MAIL$MAILFILE_PURGE_WASTE 


Deletes messages contained in the wastebasket folder of the currently open mail 
file. 


Format 

MAIL$MAILFILE_PURGE_WASTE context JnJtemJist ,out_itemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Mail file context information to be passed to other mail file routines. The context 
argument is the address of a longword that contains mail file context information. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MAILFILE_RECLAIM 

The Boolean item code MAIL$_MAILFILE_RECLAIM specifies that 
MAIL$MAILFILE_PURGE_WASTE purge the wastebasket folder and reclaim 
deleted space in the mail file. 

Specify the value 0 in the buffer length field of the item descriptor. 

MAIL$_MAILFILE_RECLAIM explicitly requests a reclaim operation and 
overrides the deleted bytes threshold regardless of the number of deleted bytes 
during a mail file purge operation. 
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outjtemjist 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

MAIL$_MAILFILE_DATA_RECLAIM 

When you specify MAIL$_MAILFILE_DATA_RECLAIM, MAIL$MAILFILE_ 
PURGE_WASTE returns the number of data buckets reclaimed during the 
reclaim operation as a longword value. 

MAIL$_MAILFILE_DATA_SCAN 

When you specify MAIL$_MAILFILE_DATA_SCAN, MAIL$MAILFILE_PURGE_ 
WASTE returns the number of data buckets scanned during the reclaim operation 
as a longword value. 

MAIL$_MAILFILEJNDEX_RECLAIM 

When you specify MAIL$_MAILFILE_INDEX_RECLAIM, the Mail utility returns 
the number of index buckets reclaimed during a reclaim operation as a longword 
value. 

MAIL$_MAILFILE_DELETED_BYTES 

When you specify MAIL$_MAILFILE_DELETED_BYTES, MAIL$MAILFILE_ 
PURGE_WASTE returns the number of bytes deleted from the mail file as a 
longword value. 

MAIL$_MAILFILE_MESSAGES_DELETED 

When you specify MAIL$_MAILFILE_MESSAGES_DELETED, 
MAIL$MAILFILE_PURGE_WASTE returns the number of deleted messages 
as a longword value. 

MAIL$_MAILFILE_TOTAL_RECLAIM 

When you specify MAIL$_MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_ 
PURGE_WASTE returns the number of bytes reclaimed due to a reclaim 
operation as a longword value. 


Description 

If you specify the MAIL$_MAILFILE_RECLAIM item descriptor, all the bytes 
deleted from the mail file by this routine are reclaimed. 


Condition Values Returned 

MAIL$_NORMAL 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 


Normal successful completion. 

The specified item code is invalid. 
The specified item length is invalid 
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MAIL$_MISREQITEM 

MAIL$_NOFILEOPEN 

MAIL$_NOTISAM 

SS$_ACCVIO 


The required item is missing. 

No mail file is currently open. 

The message file is not an indexed file. 
Access violation. 
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MAIL$MESSAGE_BEGIN 


Begins message processing. You must call this routine before calling any other 
message routines. 


Format 

MAIL$MESSAGE_BEGIN context ,in_item_list ,outJtem_list 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Message context information to be passed to various message routines. The 
context argument is the address of a longword that contains message context 
information. 

You should specify the value of this argument as 0 in the first of a sequence of 
calls to message routines. In following calls, you should specify the message 
context value returned by this routine. 

Injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input item Codes 

MAIL$_MESSAGE_FILE_CTX 

MAIL$_MESSAGE_FILE_CTX specifies the mail file context received from 
MAIL$MAILFILE_BEGIN to be passed to the message routines. The buffer 
address field of the item descriptor points to a longword that contains mail file 
context information. 

The item code MAIL$_MESSAGE_FILE_CTX is required. 
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out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

MAIL$_MESSAGE_SELECTED 

When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_BEGIN 
returns the number of messages selected as a longword value. 

Description 

MAIL$MESSAGE_BEGIN creates and initializes a message context for 
subsequent calls to message routines. 

Condition Values Returned 

MAIL$_ILLCTXADR The context block address is illegal. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

MAIL$_NOFILEOPEN The mail file is not open. 

MAIL$_WRONGCTX The context block is incorrect. 

MAIL$_WRONGFILE The specified file is incorrect in this context. 

SS$_ACCVIO Access violation. 

Any condition value returned by $GET and LIB$GET_VM. 
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MAIL$MESSAGE_COPY 


Copies messages between files or folders. 


Format 

MAIL$MESSAGE_COPY context JnJtemJist ,out_itemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. 

You should specify this argument as 0 in the first of a sequence of calls to 
message routines. In following calls, you should specify the message context 
value returned by the previous routine. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MESSAGE_BACK 

When you specify the Boolean item code MAIL$_MESSAGE_BACK, 
MAIL$MESSAGE_COPY copies the message preceding the current message. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE JD, and MAIL$_ 
MESSAGE.NEXT in the same call to MAIL$MESSAGE_COPY. 
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MAIL$_MESSAGE_DEFAULT_NAME 

MAIL$_MESSAGE_DEFAULT_NAME specifies the default file specification of a 
mail file to open in order to copy a message. The buffer address field of the item 
descriptor points to a buffer that contains a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_DELETE 

When you specify the Boolean item code MAIL$_MESSAGE_DELETE, 
MAIL$MESSAGE_COPY deletes the message in the current folder after the 
message has been copied to a destination folder. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Specify MAIL$_MESSAGE_DELETE to emulate the operation of MAIL MOVE or 
FILE command. 

MAIL$_MESSAGE_FILE_ACTION 

MAIL$_MESSAGE_FILE_ACTION specifies the address of the mail file action 
routine called if a mail file is to be created. Two parameters are passed as follows: 

• User data longword 

• Address of the descriptor of the file name to be created 

The buffer address field of the item descriptor points to a longword that denotes 
a procedure value. 

MAIL$_MESSAGE_FILENAME 

MAIL$_MESSAGE_FILENAME specifies the name of the mail file to which the 
current message will be moved. The buffer address field of the item descriptor 
points to a buffer that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_FOLDER 

MAIL$_MESSAGE_FOLDER specifies the name of the target folder for moving 
mail messages. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
The item code MAIL$_MESSAGE_FOLDER is required. 

MAIL$_MESSAGE_FOLDER_ACTION 

MAIL$_MESSAGE_FOLDER_ACTION specifies the entry point address of the 
folder action routine called if a folder is to be created. Two parameters are passed 
as follows: 

• User data longword 

• Address of a descriptor of the folder name to be created. 

The buffer address field of the item descriptor points to a longword that 
specifies a procedure value. 
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MAIL$_MESSAGEJD 

MAIL$_MESSAGE_ID specifies the message identification number of the message 
on which the operation is to be performed. The buffer address field of the item 
descriptor points to a longword that contains the message identification number. 

Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and MAIL$_ 
MESSAGE_NEXT in the same call to MAIL$MESSAGE_COPY. 

MAIL$_MESSAGE_NEXT 

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, the Mail 
utility copies the message following the current message. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, and MAIL$_ 
MESSAGE.NEXT in the same call to MAIL$MESSAGE_COPY. 

MAIL$_MESSAGE_USER_DATA 

MAIL$_MESSAGE_USER_DATA specifies data passed to the folder action and 
mail file action routines. The buffer address field of the item descriptor points 
to a user data longword. 

Specify MAIL$_MESSAGE_USER_DATA with the item codes MAIL$_MESSAGE_ 
FILE_ACTION and MAIL$_MESSAGE_FOLDER_ACTION only. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

MAIL$_MESSAGE_FILE_CREATED 

When you specify the Boolean item code MAIL$_MESSAGE_FILE_CREATED, 
MAIL$MESSAGE_COPY returns the value of the file created fiag as longword 
value. 

MAIL$_MESSAGE_FOLDER_CREATED 

When you specify the Boolean item code MAIL$_MESSAGE_FOLDER_ 
CREATED, MAIL$MESSAGE_COPY returns the value of the folder created 
fiag as a longword value. 

MAIL$_MESSAGE_RESULTSPEC 

When you specify MAIL$_MESSAGE_RESULTSPEC, MAIL$MESSAGE_COPY 
returns the mail file resultant file specification. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Description 

If you do not specify a file name, the routine copies the message to another folder 
in the currently open mail file. The target mail file must be an indexed file. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

MAIL$_MSGINFO Informational records are successully returned. 

MAIL$_MSGTEXT Text record is successfully returned. 

MAIL$_BADVALUE The specified keyword value is invalid. 

MAIL$_CONITMCOD The specified item codes define conflicting 

operations. 

MAIL$_DATIMUSED The date and time is currently used in the 

specified file. 

MAIL$_DELMSG The message is deleted. 

MAIL$_ILLCTXADR The context block address is illegal. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

MAIL$_NOFILEOPEN The mail file is not open. 

MAIL$_NOMOREREC No more records can be found. 

MAIL$_NOTREADIN The operation is invalid; you are not reading a 

message. 

MAIL$_RECTOBIG The record is too large for the MAIL buffer. 

MAIL$_WRONGCTX The context block is incorrect. 

MAIL$_WRONGFILE The specified file is incorrect in this context. 

SS$_IVDEVNAM The device name is invalid. 

SS$_ACCVIO Access violation. 

Any condition value returned by $CONNECT, $CREATE, $OPEN, $WRITE, 
$READ, and $PUT. 
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MAIL$MESSAGE_DELETE 


Deletes a specified message from the currently selected folder. 


Format 

MAIL$MESSAGE_DELETE context JnJtemJist ,out_itemJist 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 

Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information. 

in_item_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MESSAGEJD 

MAIL$_MESSAGE_ID specifies the message identification number of the message 
on which the operation is to be performed. The buffer address field points to a 
longword that contains the message identification number. 

The item code MAIL$_MESSAGE_ID is required. 

out_item_list 

OpenVMS usage 
type 
access 
mechanism 


itmlst_3 
longword 
write only 
by reference 
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Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 

Output Item Codes 

None. 

Description 

When you delete a message from a selected folder, it is moved to the wastebasket 
folder. You cannot delete a message from the wastebasket folder. You must use 
the MAIL$MAILFILE_PURGE_WASTE routine to empty the wastebasket folder. 

Condition Values Returned 

SS$NORMAL Normal successful completion. 

MAIL$_ILLCTXADR The context block address is illegal. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

MAIL$_NOFILEOPEN The mail file is not open. 

MAIL$_WRONGCTX The context block is incorrect. 

MAIL$_WRONGFILE The specified file is incorrect in this context. 

SS$_ACCVIO Access violation. 
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MAIL$MESSAGE_END 


Ends message processing. 


Format 

MAIL$MESSAGE_END context JnJtemJist ,outJtemJist 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. If message processing ends successfully, 
the argument context is changed to 0 . 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. This routine does not use the in_ 
itemjist argument. 

out_ltemJist 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. This routine 
does not use the out_item_list argument. 


Description 

The MAIL$MESSAGE_END routine deallocates the message context created by 
MAIL$MESSAGE_BEGIN as well as any dynamic memory allocated by other 
message routines. 
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Condition Values Returned 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 

Any condition value returned by LIB$FREE_VM. 
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MAIL$MESSAGE_GET 


Retrieves a message from the set of currently selected messages. 


Format 

MAIL$MESSAGE_GET context JnJtemJist ,out_itemJist 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 

Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MESSAGE_AUTO_NEWMAIL 

When you specify the Boolean item code MAIL$_MESSAGE_AUTO_NEWMAIL, 
MAIL$MESSAGE_GET places a new message in the MAIL folder as it is read 
automatically. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

MAIL$_MESSAGE_BACK 

When you specify the Boolean item code MAIL$_MESSAGE_BACK, 
MAIL$MESSAGE_GET reads the message identification number of a specified 
message to return the first record of the preceding message. 
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Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ 
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same 
call to MAIL$MESSAGE_GET. 

MAIL$_MESSAGE_CONTINUE 

When you specify the Boolean item code MAIL$_MESSAGE_CONTINUE, 
MAIL$MESSAGE_GET reads the message identification number of a specified 
message to return the next text record of the current message. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ 
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same 
call to MAIL$MESSAGE_GET. 

MAIL$_MESSAGEJD 

MAIL$_MESSAGE_ID specifies the message identification number of a message 
on which an operation is to be performed. The buffer address field of the item 
descriptor points to a longword that contains the message identification number. 

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ 
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same 
call to MAIL$MESSAGE_GET. 

M Al L$_M ESS AG E_N EXT 

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, 
MAIL$MESSAGE_GET reads the message identification number of a specified 
message to return the first record of the message following the current message. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ 
CONTINUE, MAIL$_MESSAGE_ID, and MAIL$_MESSAGE_NEXT in the same 
call to MAIL$MESSAGE_GET. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 
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Output Item Codes 

MAIL$_MESSAGE_BINARY_DATE 

When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_GET 
returns the message arrival date as a quadword binary value. 

MAIL$_MESSAGE_CC 

When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_GET returns the 
CC: field of the current message. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_CURRENTJD 

When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_GET 
returns the message identification number of the current message. The buffer 
address field of the item descriptor points to a longword that receives the 
message identifier number. 

MAIL$_MESSAGE_DATE 

When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_GET returns the 
message creation date string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

M Al L$_M ESS AG E_EXTI D 

MAIL$MESSAGE_EXTID specifies the external message identification number of 
the current message. The buffer address field of the item descriptor points to a 
buffer that contains a character string 0 to 255 characters long. 

MAIL$_MESSAGE_FROM 

When you specify MAIL$_MESAGE_FROM, MAIL$MESSAGE_GET returns 
the From: field of the specified message. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_RECORD 

When you specify MAIL$_MESSAGE_RECORD, MAIL$MESSAGE_GET returns 
a record of the message. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_RECORD is valid only when specified with the item code 
MAIL$_MESSAGE_CONTINUE. 

Do not specify MAIL$_MESSAGE_RECORD with the following item codes: 

• MAIL$_MESSAGE_BACK 

• MAIL$_MESSAGE_ID 

• MAIL$_MESSAGE_NEXT 
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MAIL$_MESSAGE_RECORD_TYPE 

When you specify MAIL$_MESSAGE_RECORD_TYPE, MAIL$MESSAGE_GET 
returns the record type. A record may be either header information (MAIL$_ 
MESSAGE.HEADER) or text (MAIL$_MESSAGE_TEXT). The buffer address 
field of the item descriptor points to a word that receives the record type. 

MAIL$_MESSAGE_RETURN_FLAGS 

When you specify MAIL$_MESSAGE_RETURN_FLAGS, MAIL$MESSAGE_GET 
returns the MAIL system fiag for the current message as a 2-byte bitmask value. 

MAIL$_MESSAGE_SENDER 

When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_GET returns 
the name of the sender of the current message. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_SIZE 

When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_GET returns the 
size in records of the current message as a longword value. 

MAIL$_MESSAGE_SUBJECT 

When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_GET returns 
the Subject: field of the specified message. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

M AI L$_M ESS AG E_TO 

When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_GET returns the To: 
field of the specified message. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

Description 

The first time the MAIL$MESSAGE_GET routine is called, the message 
information is returned for the first requested message, and the status returned 
is MAIL$_MSGINFO. Subsequent calls to MAIL$MESSAGE_GET with the 
MAIL$_MESSAGE_CONTINUE item code return the message text records with 
the status MAIL$_MSGTEXT, until no more records are left, when MAIL$_ 
NOMOREREC is returned. 


Condition Values Returned 

MAIL$_MSGINFO 

MAIL$_MSGTEXT 

MAIL$_ILLCTXADR 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 


Informational records are successully returned 
Text record is successfully returned. 

The context block address is illegal. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 
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MAIL$_NOFILEOPEN 

MAIL$_NOMOREREC 

MAIL$_NOTREADIN 

mail$_rectobig 

MAIL$_WRONGCTX 

MAIL$_WRONGFILE 

SS$_ACCVIO 

Any condition value returned 


The mail file is not open. 

No more records can be found. 

The operation is invalid; you are not reading a 
message. 

The record is too large for the MAIL buffer. 
The context block is incorrect. 

The specified file is incorrect in this context. 
Access violation, 
by $FIND and $UPDATE. 
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MAIL$MESSAGEJNFO 


Obtains information about a specified message contained in the set of currently 
selected messages. 


Format 

MAIL$MESSAGE_INFO context JnJtemJist ,out_itemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. 

in_item_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0. 

Input Item Codes 

MAIL$_MESSAGE_BACK 

When you specify Boolean item code MAIL$_MESSAGE_BACK, 
MAIL$MESSAGE_INFO reads the message identification number of the current 
message and returns the message preceding the current message. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify MAIL$_MESSAGE_BACK,MAIL$_MESSAGE_ID, and MAIL$_ 
MESSAGE.NEXT in the same call to MAIL$MESSAGE_INFO. 
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MAIL$_MESSAGEJD 

MAIL$_MESSAGE_ID specifies the message identification number of the message 
on which the operation is to be performed. The buffer address field of the item 
descriptor points to a longword that contains the message identification number. 

Do not specify MAIL$_MESSAGE_BACK,MAIL$_MESSAGE_ID, and MAIL$_ 
MESSAGE_NEXT in the same call to MAIL$MESSAGE_INFO. 

MAIL$_MESSAGE_NEXT 

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, 
MAIL$MESSAGE_INFO reads the message identification number of the current 
message and returns the message that follows it. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify MAIL$_MESSAGE_BACK,MAIL$_MESSAGE_ID, and MAIL$_ 
MESSAGE.NEXT in the same call to MAIL$MESSAGE_INFO. 

outjtemjist 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

MAIL$_MESSAGE_BINARY_DATE 

When you specify MAIL$_MESSAGE_BINARY_DATE, MAIL$MESSAGE_INFO 
returns the message arrival date as a quadword binary value. 

MAIL$_MESSAGE_CC 

When you specify MAIL$_MESSAGE_CC, MAIL$MESSAGE_INFO returns the 
CC: field of the current message. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_CURRENTJD 

When you specify MAIL$_MESSAGE_ID, MAIL$MESSAGE_INFO returns the 
message identification number of the current message. The buffer address 
field of the item descriptor points to a longword that receives the message 
identification number of the current message. 

MAIL$_MESSAGE_DATE 

When you specify MAIL$_MESSAGE_DATE, MAIL$MESSAGE_INFO returns 
the message creation date string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$_MESSAGE_EXTID 

When you specify MAIL$_MESSAGE_EXTID, MAIL$MESSAGE_INFO returns 
the external identification number of the current message as a string. The buffer 
address field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_FROM 

When you specify MAIL$_MESSAGE_FROM, MAIL$MESSAGE_INFO returns 
the From: field of the specified message. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_REPLY_PATH 

When you specify MAIL$_MESSAGE_REPLY_PATH, MAIL$MESSAGE_INFO 
returns the reply path of the specified message. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_RETURN_FLAGS 

When you specify MAIL$_MESSAGE_RETURN_FLAGS, MAIL$MESSAGE_ 
INFO returns the MAIL system flag values for the current message as a 2-byte 
bitvector value. 

MAIL$_MESSAGE_SENDER 

When you specify MAIL$_MESSAGE_SENDER, MAIL$MESSAGE_INFO returns 
the name of the sender of the current message. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_SIZE 

When you specify MAIL$_MESSAGE_SIZE, MAIL$MESSAGE_INFO returns the 
size of the current message in records as a longword value. 

MAIL$_MESSAGE_SUBJECT 

When you specify MAIL$_MESSAGE_SUBJECT, MAIL$MESSAGE_INFO 
returns the Subject: field of the specified message. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_TO 

When you specify MAIL$_MESSAGE_TO, MAIL$MESSAGE_INFO returns the 
To: field of the specified message. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Description 

MAIL$MESSAGE_INFO obtains information about a particular message. 
MAIL$MESSAGE_GET retrieves a message from the set of currently selected 
messages. 

The first call to MAIL$MESSAGE_GET passes control to MAIL$MESSAGE_ 
INFO. Subsequent calls that include the MAIL$_MESSAGE_CONTINUE item 
code return text records. 

Condition Values Returned 


MAIL$_CONITMCOD 

MAIL$_DELMSG 

MAIL$_ILLCTXADR 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

MAIL$_NOFILEOPEN 

MAIL$_NOMOREMSG 

MAIL$_WRONGCTX 

MAIL$_WRONGFILE 

SS$_ACCVIO 

Any condition value returned 


The specified item codes define conflicting 
operations. 

The message is deleted. 

The context block address is illegal. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

The mail file is not open. 

No more messages. 

The context block is incorrect. 

The specified file is incorrect in this context. 
Access violation, 
by LIB$GET_VM. 
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MAIL$MESSAGE_MODIFY 


Modifies information in the message header. 


Format 

MAIL$MESSAGE_MODIFY context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. 

in_item_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MESSAGE_BACK 

When you specify the Boolean item code MAIL$_MESSAGE_BACK, 
MAIL$MESSAGE_MODIFY reads the message identification number of the 
specified message in order to return the first record in the preceding message. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, 
and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_MODIFY. 
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MAIL$_MESSAGE_FLAGS 

MAIL$_MESSAGE_FLAGS specifies system flags for new mail. The buffer 
address field of the item descriptor points to a word that contains bitvector 
offsets. The following offsets can be used to modify the 2-byte bitvector: 

• MAIL$V_replied 

• MAIL$V_marked 

MAIL$_MESSAGEJD 

MAIL$_MESSAGE_ID specifies the message identification number of the message 
on which an operation is to be performed. The buffer address field of the item 
descriptor points to a longword that contains the message identification number. 

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, 
and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_MODIFY. 

MAI L$_M ESS AG E_N EXT 

When you specify the Boolean item code MAIL$_MESSAGE_NEXT, 
MAIL$MESSAGE_NEXT reads the message identification number of a message 
and returns the first record in the message following the current message. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify the item codes MAIL$_MESSAGE_BACK, MAIL$_MESSAGE_ID, 
and MAIL$_MESSAGE_NEXT in the same call to MAIL$MESSAGE_MODIFY. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0 . 


Output Item Codes 

MAIL$_MESSAGE_CURRENTJD 

When you specify MAIL$_MESSAGE_CURRENT_ID, MAIL$MESSAGE_ 
MODIFY returns the message identification number of the current message. 
The buffer address field of the item descriptor points to a longword that 
receives the message identification number. 

Condition Values Returned 


MAIL$_CONITMCOD 

MAIL$_DELMSG 

MAIL$_ILLCTXADR 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 


The specified item codes define conflicting 
operations. 

The message is deleted. 

The context block address is illegal. 

The specified item code is invalid. 

The specified item length is invalid. 
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MAIL$_MISREQITEM The required item is missing. 

MAIL$_NOFILEOPEN The mail file is not open. 

MAIL$_NOMOREMSG No more messages. 

MAIL$_WRONGCTX The context block is incorrect. 

MAIL$_WRONGFILE The specified file is incorrect in this context. 

SS$_ACCVIO Access violation. 

Any condition value returned by $FIND and $UPDATE. 
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MAIL$MESSAGE_SELECT 


Selects a message or messages from the currently open mail file. Before you 
attempt to read a message, you must select it. 


Format 

MAIL$MESSAGE_SELECT context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Message context information to be passed to message routines. The context 
argument is the address of a longword that contains message context information 
returned by MAIL$MESSAGE_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0 . 

Input Item Codes 

MAIL$_MESSAGE_BEFORE 

When you specify MAIL$_MESSAGE_BEFORE, MAIL$MESSAGE_SELECT 
selects a message received before a specified date and time. The buffer address 
field of the item descriptor points to a buffer that contains a character string 0 to 
255 characters long in absolute time. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$_MESSAGE_CC_SUBSTRING 

MAIL$_MESSAGE_CC_SUBSTRING specifies a character string that must 
match a substring contained in the CC: field of the specified message. If the 
strings match, the message is selected. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_FLAGS 

MAIL$_MESSAGE_FLAGS specifies bit masks that must be initialized to 1. 

MAIL$_MESSAGE_FLAGS_MBZ 

MAIL$_MESSAGE_FLAGS_MBZ specifies MAIL system flags that must be set to 

0 . 

MAIL$_MESSAGE_FOLDER 

MAIL$_MESSAGE_FOLDER specifies the name of the folder that contains 
messages to be selected. 

The buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
This item code is required. 

MAIL$_MESSAGE_FROM_SUBSTRING 

MAIL$_MESSAGE_FROM_SUBSTRING specifies a user-specified character 
string that must match the substring contained in the From: field of a specified 
message. If the strings match, the message is selected. 

The buffer address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_SINCE 

When you specify MAIL$_MESSAGE_SINCE, the Mail utility selects a message 
received since a specified date and time. 

The buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long in absolute time. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_TO_SUBSTRING 

MAIL$_MESSAGE_TO_SUBSTRING specifies a user-specified character string 
that must match a substring contained in the To: field of a specified message. If 
the strings match, the message is selected. 

The buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_MESSAGE_SUBJ_SUBSTRING 

MAIL$_MESSAGE_SUBJ_SUBSTRING specifies a user-specified character 
string that must match a substring contained in the Subject: field of a specified 
message. If the strings match, the message is selected. 
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The buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

MAIL$_MESSAGE_SELECTED 

When you specify MAIL$_MESSAGE_SELECTED, MAIL$MESSAGE_SELECT 
returns the number of selected messages as a longword value. 

Description 

MAIL$MESSAGE_SELECT deselects previously selected messages whether or 
not you request a valid selection. 

Condition Values Returned 

MAIL$_ILLCTXADR The context block address is illegal. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_INVQUAVAL The specified qualifier is invalid 

MAIL$_MISREQITEM The required item is missing. 

MAIL$_NOFILEOPEN The mail file is not open. 

MAIL$_NOTEXIST The specified folder does not exist. 

MAIL$_NOTISAM The operation applies only to indexed files. 

MAIL$_WRONGCTX The context block is incorrect. 

MAIL$_WRONGFILE The specified file is incorrect in this context. 

SS$_ACCVIO Access violation. 

Any condition value returned by LIB$GET_VM. 
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MAIL$SEND_ABORT 


Cancels a currently executing send operation. 


Format 

MAIL$SEND_ABORT context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. This routine does not use the in_ 
itemjist argument. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. This routine 
does not use the out_itemJist argument. 

Description 

MAIL$SEND_ABORT is useful when, for example, the user enters the key 
sequence Ctrl/c during the execution of MAIL$SEND_MESSSAGE. 


MAIL-78 



Mail Utility Routines 
MAIL$SEND_ABORT 


Condition Values Returned 

SS$NORMAL 


Normal successful completion. 
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MAIL$SEND_ADD__ADDRESS 


Adds an address to the address list. If an address list does not exist, 
MAIL$SEND_ADD_ADDRESS creates one. 


Format 


MAIL$SEND_ADD_ADDRESS context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_BEGIN. 

in_item_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0. 

Input Item Codes 

MAIL$_SEND_USERNAME 

MAIL$_SEND_USERNAME specifies that the Mail utility add a specified 
username to the address list. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

The item code MAIL$_SEND_USERNAME is required. 
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MAIL$_SEND_USERNAME_TYPE 

MAIL$_SEND_USERNAME_TYPE specifies the type of username added to the 
address list. The buffer address field of the item descriptor points to a word 
that contains the username type. 

There are two types of usernames, as follows: 

• Username specified as a To: address (default) 

• Username specified as a CC: address 

_ Note _ 

Currently, the symbols MAIL$_TO and MAIL$_CC define username types. 


outjtemjist 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out__ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

None. 


Description 

If you do not specify a MAIL$_SEND_USERNAME_TYPE, MAIL$SEND_ADD. 
ADDRESS uses MAIL$_TO. You can specify only one username per call to 
MAIL$SEND_ADD_ADDRESS. 

Condition Values Returned 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 

Any condition values returned by LIB$TPARSE. 
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MAIL$SEND^ADD^ATTRIBUTE 


Adds an attribute such as ’Subject’, ’To’ and so forth, to the message you are 
currently constructing. 


Format 

MAIL$SEND_ADD_ATTRIBUTE context ,injtemjist ,out_item_list 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_BEGIN. 

You should specify this argument as 0 in the first of a sequence of calls to MAIL 
routines. In following calls, you should specify the SEND context value returned 
by the previous routine. 

in_itemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The in_item_list argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0. 

Input Item Codes 

MAIL$_SEND_CC_LINE 

MAIL$_SEND_CC_LINE specifies a descriptor of the CC: field text. The buffer 
address field of the item descriptor points to a buffer that contains a character 
string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$_SEND_FROM_LINE 

MAIL$_SEND_FROM_LINE specifies a descriptor of the From: field text of the 
message to be sent. The buffer address field of the item descriptor points to a 
buffer that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

The SYSPRV privilege is required to alter the From: of a message. 

MAIL$_SEND_SUBJECT 

MAIL$_SEND_SUBJECT specifies a descriptor of the Subject: field text of a 
message to be sent. The buffer address field of the item descriptor points to a 
buffer that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_SEND_TO_LINE 

MAIL$_SEND_TO_LINE specifies a descriptor of the To: field text of the 
message. The buffer address field of the item descriptor points to a buffer 
that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

out_itenn_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out__ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

None. 


Description 

If you do not specify a To: line, the Mail utility supplies a To: line composed 
of usernames on the To: address list. If you do not specify a CC: line, the Mail 
utility supplies a CC: line composed of usernames on the CC: address list. In 
either of the above cases, commas separate the usernames used. 

To add a message’s From: field, you must have the SYSPRV, and the MAIL 
DECnet object must have SYSPRV privilege on OUTGOING CONNECT (users 
may set the DECnet object privileges at their discretion). 
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Condition Values Returned 

Normal successful completion. 

The specified item code is invalid. 
The specified item length is invalid. 
The required item is missing. 
Access violation. 


SS$NORMAL 
MAIL$_INVITMCOD 
MAIL$_INVITMLEN 
MAIL$_MISREQITEM 
SS$ ACCVIO 
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MAIL$SEND_ADD_BODYPART 


Builds the body of a message. 


Format 

MAIL$SEND_ADD_BODYPART context ,in_item_list ,outJtem_list 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 

Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The in_itemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0. 

See MAIL$SEND_BEGIN for a description of an input item descriptor. 

Input Item Codes 

MAIL$_SEND_DEFAULT_NAME 

MAIL$_SEND_DEFAULT_NAME specifies the default file specification of a text 
file to be opened. The buffer address field of the item descriptor points to a 
buffer that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_SEND_FID 

MAIL$_SEND_FID specifies the file identifier of the text file to be opened. The 
buffer address field of the item descriptor points to a buffer that contains the 
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file identifier. Note that the MAIL$_SEND_FID item code and the MAIL$_ 
SEND_FILNAME item code are mutually exclusive. 

MAIL$_SEND_FILENAME 

MAIL$_SEND_FILENAME specifies the input file specification of the text file 
to be opened. The buffer address field of the item descriptor points to a buffer 
that receives a character string 0 to 255 characters long. Note that the MAIL$_ 
SEND_FILNAME item code and the MAIL$_SEND_FID item code and are 
mutually exclusive. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_SEND_RECORD 

MAIL$_SEND_RECORD specifies a descriptor of a text record to be added to the 
body of the message. The buffer address field of the item descriptor points to a 
buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

When creating a message, do not specify MAIL$_SEND_RECORD in the same 
call (or series of calls) to MAIL$SEND_ADD_BODYPART with the following item 
codes: 

• MAIL$_SEND_FID 

• MAIL$_SEND_FILENAME 

_ Note _ 

Do not use the MAIL$_SEND_RECORD item code with the MAIL$SEND_ 
ADD_BODYPART routine called from a detached process because the 
routine creates a temporary file in SYS$SCRATCH that is inaccessible to 
the detached process. 


out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

mail$_send_resultspec 

When you specify MAIL$_SEND_RESULTSPEC, MAIL$SEND_ADD_BODYPART 
returns the resultant file specification identified with MAIL$_SEND_FILENAME. 
The buffer address field of the item descriptor points to a buffer that receives a 
character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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Description 

You can use MAIL$SEND_ADD_BODYPART to specify a file that contains the 
entire message or to add a single record to a message. If the message is contained 
in a file, you call MAIL$SEND_ADD_BODYPART once, specifying the filename. 

If you want to add to the message record-by-record, you can call MAIL$SEND_ 
ADD_BODYPART repeatedly, specifying a different record each time until you 
complete the message. 

You cannot specify both a filename and a record for the same message. You can 
specify either MAIL$_SEND_FILENAME or MAIL$_SEND_FID once, or you can 
specify MAIL$_SEND_RECORD one or more times. 

Condition Values Returned 


SS$NORMAL 

MAIL$_CONITMCOD 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

MAIL$_OPENIN 

SS$_ACCVIO 


Normal successful completion. 

The specified item codes define conflicting 
operations. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

The required file is missing. 

Access violation. 
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MAIL$SEND_BEGIN 


Initiates processing to send a message to the users on the address list. You must 
call MAIL$SEND_BEGIN before you call any other send routine. 


Format 

MAIL$SEND_BEGIN context JnJtemJist ,out_itemJist 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Send context information to be passed to other send routines. The context 
argument is the address of a longword that contains send context information. 

You should specify the value of this argument as 0 in the first of a sequence of 
calls to send routines. In following calls, you should specify the send context 
value returned by this routine. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0. 

Input Item Codes 

MAIL$_SEND_PERS_NAME 

MAIL$_SEND_NO_PERS_NAME 

Note that you must specify only one of these item codes. An error is generated if 
you specifify both item codes. MAIL$_SEND_PERS_NAME specifies the personal 
name text to be used in the message header. The buffer address field of the 
item descriptor points to a buffer that contains a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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The Boolean item code MAIL$_SEND_NO_PERS_NAME specifies that no 
personal name string be used during message construction. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

out_itemJist 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

MAIL$_SEND_COPY_FORWARD 

When you specify the Boolean item code MAIL$_SEND_COPY_FORWARD, 
MAIL$SEND_BEGIN returns the value of the caller's copy forward fiag as a 
longword value. 

MAIL$_SEND_COPY_SEND 

When you specify the Boolean item code MAIL$_SEND_COPY_SEND, 
MAIL$SEND_BEGIN returns the value of the caller's copy send fiag as a 
longword value. 

MAIL$_SEND_COPY_REPLY 

When you specify the Boolean item code MAIL$_SEND_COPY_REPLY, 
MAIL$SEND_BEGIN returns the value of the caller's copy reply fiag as a 
longword value. 

MAIL$_SEND_USER 

When you specify MAIL$_SEND_USER, MAIL$SEND_BEGIN returns the 
process owner's username. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


Description 

MAIL$SEND_BEGIN creates and initializes a send context for subsequent calls 
to send routines. 


Condition Values Returned 

SS$NORMAL 

MAIL$_CODERR 

MAIL$_CONITMCOD 

MAIL$_ILLPERNAME 

MAIL$_INVITMCOD 


Normal successful completion. 

Internal system error. 

The specified item codes perform conflicting 
operations. 

The specified personal name string is illegal. 
The specified item code is invalid. 
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MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 

Any condition values returned by $GETJPIW, LIB$FREE_VM, and LIB$GET 
VM. 
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MAIL$SEND_END 


Terminates send processing. 


Format 


MAIL$SEND_END context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 
MAIL$SEND_BEGIN. 

If send processing is successfully terminated, the value of the context argument 
is changed to 0. 

In_item_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. This routine does not use the in_ 
itemjist argument. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. This routine 
does not use the out_itemJist argument. 
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Description 

The MAIL$SEND_END routine deallocates the send context as well as any 
dynamic memory allocated by previous send routine calls. 

Condition Vaiues Returned 

completion 
code is invalid, 
length is invalid, 
is missing. 


SS$_NORMAL 

MAIL$_INVITMCOD 

MAIL$_INYITMLEN 

MAIL$_MISREQITEM 

SS$_ACCVIO 


Normal successful 
The specified item 
The specified item 
The required item 
Access violation, 
by LIB$FREE_VM 


Any condition value returned 
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MAIL$SEND_MESSAGE 


Begins the actual sending of the message after the message has been constructed. 


Format 

MAIL$SEND_MESSAGE context JnJtemJist ,outJtem_list 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Send context information to be passed to send routines. The context argument 
is the address of a longword that contains send context information returned by 

mail$send_begin. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list is terminated by longword value of 0. 

Input Item Codes 

MAIL$_SEND_ERROR_ENTRY 

MAIL$_SEND_ERROR_ENTRY specifies the longword address of an entry point 
to process errors during a send operation. The descriptor of the recipient that 
failed, the address of the signal array, and the user-specified data are passed as 
input to the routine. 

MAIL$_SEND_SUCCESS_ENTRY 

MAIL$_SEND_SUCCESS_ENTRY specifies the longword address of an entry 
point to process successes during a send operation. The descriptor of the recipient 
that succeeded, the address of the signal array, and the user-specified data are 
passed as input to the routine. 
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MAIL$_SEND_USER_DATA 

MAIL$_SEND_USER_DATA specifies a longword that MAIL$SEND_MESSAGE 
passes to the SEND action routines. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

None. 


Description 

The MAIL$SEND_MESSAGE routine sends a message built with the 
MAIL$SEND_ADD_BODYPART routine to every user on the address list. If 
you have not used MAIL$SEND_ADD_BODYPART to construct a message, 
MAIL$SEND_MESSAGE sends only a message header. 

If MAIL$SEND_MESSAGE encounters errors sending to an addressee, it calls 
the routine specified by MAIL$_SEND_ERROR_ENTRY. Otherwise, it calls the 
routine specified by MAIL$_SEND_SUCCESS_ENTRY. 

If either routine is not specified, MAIL$SEND_MESSAGE calls no other routines. 

Condition Values Returned 


MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

SS$_ACCVIO 

Any condition value returned 


The specified item code is invalid. 
The specified item length is invalid. 
The required item is missing. 
Access violation, 
by $CONNECT. 
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MAIL$USER_BEGIN 


Initiates access to the MAIL common user database. You must call MAIL$USER 
BEGIN before you call any other user routines. 


Format 

MAIL$USER_BEGIN context JnJtemJist ,outJtem_list 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

User context information to be passed to other user routines. The context 
argument is the address of a longword that contains user context information. 

You should specify the value of this argument as 0 in the first of a sequence of 
calls to MAIL routines. In following calls, you should specify the user context 
value returned by the previous routine. 

in_item_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. This routine does not use the in_ 
itemjist argument. 

out_item_llst 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. The following diagram depicts the format of a single item 
descriptor: 
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Output item Codes 

MAIL$_USER_AUTO_PURGE 

When you specify the Boolean item code MAIL$_USER_AUTO_PURGE, 
MAIL$USER_BEGIN returns the value of the automatic purge mail flag as a 
longword value. 

MAIL$_USER_CAPTIVE 

When you specify the Boolean item code MAIL$_USER_CAPTIVE, MAIL$USER_ 
BEGIN returns the value of the UAF CAPTIVE flag as a longword value. 

MAIL$_USER_CC_PROMPT 

When you specify the Boolean item code MAIL$_USER_CC_PROMPT, 
MAIL$USER_BEGIN returns the value of the cc prompt flag as a longword 
value. 

MAIL$_USER_COPY_FORWARD 

When you specify the Boolean item code MAIL$_USER_COPY_FORWARD, 
MAIL$USER_BEGIN returns the value of the copy self forward flag as a 
longword value. 

MAIL$_USER_COPY_REPLY 

When you specify the Boolean item code MAIL$_USER_COPY_REPLY, 
MAIL$USER_BEGIN returns the value of the copy self reply flag as a longword 
value. 

MAIL$_USER_COPY_SEND 

When you specify the Boolean item code MAIL$_USER_COPY_SEND, 
MAIL$USER_BEGIN returns the value of the copy self send flag as a longword 
value. 

MAIL$_USER_FORWARDING 

When you specify MAIL$_USER_FORWARDING, MAIL$USER_BEGIN returns 
the forwarding address string. The buffer address fleld of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_FORM 

When you specify MAIL$_USER_FORM, MAIL$USER_BEGIN returns the 
default print form string. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_FULL_DIRECTORY 

When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_BEGIN 
returns complete directory path of the MAIL subdirectory. The buffer address 
field of the item descriptor points to a buffer that receives a character string 0 to 
255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_NEW_MESSAGES 

When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_BEGIN 
returns the new message count. The buffer address field of the item descriptor 
points to a word that receives the new message count. 
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MAIL$_USER_PERSONAL_NAME 

When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_BEGIN 
returns the personal name string. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_QUEUE 

When you specify MAIL$_USER_QUEUE, MAIL$USER_BEGIN returns the 
default print queue name. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_RETURN_USERNAME 

When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_BEGIN 
returns the username string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_SUB_DIRECTORY 

When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_BEGIN 
returns the subdirectory specification. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


Description 

MAIL$USER_BEGIN creates and initializes a user database context for 
subsequent calls to other user routines. 

Condition Values Returned 


SS$NORMAL 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

SS$_ACCVIO 


Normal successful 
The specified item 
The specified item 
The required item 
Access violation. 


completion, 
code is invalid, 
length is invalid, 
is missing. 
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MAIL$USER_DELETEJNFO 


Removes a record from the user profile database. 


Format 


MAIL$USER_DELETEJNFO context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

User context information to be passed to send routines. The context argument 
is the address of a longword that contains user context information returned by 
MAIL$USER_BEGIN. 

injtem_list 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list must include at least one device item descriptor. The item list is 
terminated by longword value of 0. 

Input Item Codes 

MAIL$_USER_USERNAME 

MAIL$_USER_USERNAME specifies the record to be deleted from the user 
profile database. The buffer address field of the item descriptor points to a 
buffer that contains the username string encoded in a character string 0 to 31 
characters long. 

Specify a value from 0 to 31 in the buffer length field of the item descriptor. 

The item code MAIL$_USER_USERNAME is required. 
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out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

None. 

Description 

To delete a record from the user profile database, you must have SYSPRV 
privilege. 

Condition Vaiues Returned 

SS$NORMAL 
MAIL$_INVITMCOD 
MAIL$_INVITMLEN 
MAIL$_MISREQITEM 
MAIL$_NOSUCHUSR 
MAIL$_NOSYSPRV 
SS$_ACCVIO 


Normal successful completion. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

The specified username is not valid. 

The operation requires the SYSPRV privilege. 
Access violation. 
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MAIL$USER_END 


Terminates access to the user profile database. 


Format 


MAIL$USER_END context JnJtemJist ,outJtemJist 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

User context information to be passed to user routines. The context argument is 
the address of a longword that contains user context information. 

If the Mail utility terminates access to the user profile database successfully, the 
value of the argument context is changed to 0. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. This routine does not use the in_ 
itemjist argument. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. This routine 
does not use the out^itemJist argument. 


Description 

The MAIL$USER_END routine deallocates the user database context created by 
MAIL$USER_BEGIN as well as all dynamic memory allocated by previous user 
routines. 
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Condition Values Returned 

SS$_NORMAL Normal successful completion. 

MAIL$_INVITMCOD The specified item code is invalid. 

MAIL$_INVITMLEN The specified item length is invalid. 

MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 

Any condition value returned by LIB$FREE_VM 
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MAIL$USER_GETJNFO 


Obtains information about a user from the user profile database. 


Format 

MAIL$USER_GET_INFO context ,in_item_list ,outJtemJist 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

User context information to be passed to user routines. The context argument 
is the address of a longword that contains user context information returned by 
MAIL$USER_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The in__itemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list must include at least one device item descriptor. The item list is 
terminated by longword value of 0. 

Input Item Codes 

MAIL$_USER_FIRST 

The Boolean item code MAIL$_USER_FIRST specifies that MAIL$USER_GET_ 
INFO return information in the user profile about the first entry in the user 
profile database. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_USER_ 
USERNAME in the same call to MAIL$USER_GET_INFO. 
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MAIL$_USER_NEXT 

The Boolean item code MAIL$_USER_NEXT specifies that MAIL$USER_GET_ 
INFO return information in the user profile about the next user. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT or MAIL$_USER_ 
USERNAME in the same call to MAIL$USER_GET_INFO. 

MAIL$_USER_USERNAME 

The item code MAIL$_USER_USERNAME points to the username string. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

Do not specify MAIL$_USER_FIRST, MAIL$_USER_NEXT and MAIL$_USER_ 
USERNAME in the same call to MAIL$USER_GET_INFO. 

out_item_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

MAIL$_USER_AUTO_PURGE 

When you specify the Boolean item code MAIL$_USER_AUTO_PURGE, 
MAIL$USER_GET_INFO returns the value of the automatic purge mail fiag 
as a longword value. 

MAIL$_USER_CC_PROMPT 

When you specify the Boolean item code MAIL$_USER_CC_PROMPT, 
MAIL$USER_GET_INFO returns the value of the CC prompt fiag as a longword 
value. 

MAIL$_USER_COPY_FORWARD 

When you specify the Boolean item code MAIL$_USER_COPY_FORWARD, 
MAIL$USER_GET_INFO returns the value of the copy self forward mail fiag as a 
longword value. 

MAIL$_USER_COPY_REPLY 

When you specify the Boolean item code MAIL$_USER_COPY_REPLY, 
MAIL$USER_GET_INFO returns the value of the copy self reply mail flag 
as a longword value. 

MAIL$_USER_COPY_SEND 

When you specify the Boolean item code MAIL$_USER_COPY_SEND, 
MAIL$USER_GET_INFO returns the value of the copy self send mail flag as 
a longword value. 
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MAIL$_USER_EDITOR 

When you specify MAIL$_USER_EDITOR, MAIL$USER_GET_INFO returns the 
name of the default editor. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_FORWARDING 

When you specify MAIL$_USER_FORWARDING, MAIL$USER_GET_INFO 
returns the forwarding address. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_FORM 

When you specify MAIL$_USER_FORM, MAIL$USER_GET_INFO returns the 
default print form string. The buffer address field of the item descriptor points 
to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_FULL_DIRECTORY 

When you specify MAIL$_USER_FULL_DIRECTORY, MAIL$USER_GET_INFO 
returns the complete directory path of the MAIL subdirectory string. The buffer 
address field of the item descriptor points to a buffer that receives a character 
string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_NEW_MESSAGES 

When you specify MAIL$_USER_NEW_MESSAGES, MAIL$USER_GET_INFO 
returns the new messages count. The buffer address field of the item descriptor 
points to a word that receives the new message count as a longword value. 

MAIL$_USER_PERSONAL_NAME 

When you specify MAIL$_USER_PERSONAL_NAME, MAIL$USER_GET_ 

INFO returns the personal name string. The buffer address field of the item 
descriptor points to a buffer that receives a character string 0 to 255 characters 
long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_QUEUE 

When you specify MAIL$_USER_QUEUE, MAIL$USER_GET_INFO returns the 
default print queue name string. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

MAIL$_USER_RETURN_USERNAME 

When you specify MAIL$_USER_RETURN_USERNAME, MAIL$USER_GET_ 
INFO returns the username. The buffer address field of the item descriptor 
points to a buffer that receives a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 
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MAIL$_USER_SUB_DIRECTORY 

When you specify MAIL$_USER_SUB_DIRECTORY, MAIL$USER_GET_INFO 
returns the MAIL subdirectory specification string. The buffer address field of 
the item descriptor points to a buffer that receives a character string 0 to 255 
characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 


Description 

The MAIL$USER_GET_INFO routine returns information about specified entries 
in the user profile database. If you do not specify a user name, MAIL$USER_ 
GET_INFO returns information about the user name associated with the calling 
process. To obtain information about a user name other than that associated with 
the calling process, you need the SYSNAM privilege. 

Condition Values Returned 


SS$NORMAL 

MAIL$_CONITMCOD 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 

MAIL$_MISREQITEM 

MAIL$_NOSUCHUSR 

MAIL$_NOSYSPRV 

SS$_ACCVIO 


Normal successful completion. 

The specified item codes perform conflicting 
operations. 

The specified item code is invalid. 

The specified item length is invalid. 

The required item is missing. 

The specified username is invalid. 

The specified operation requires the SYSPRV 
privilege. 

Access violation. 
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MAIL$USER_SETJNFO 


Adds or modifies a specified user record in the user profile database. 

Format 

MAIL$USER_SET_INFO context JnJtemJist ,outJtemJist 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. All utility routines return a condition value in RO. 
Condition values that can be returned by this routine are listed under Condition 
Values Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

User context information to be passed to user routines. The context argument 
is the address of a longword that contains user context information returned by 
MAIL$USER_BEGIN. 

injtemjist 

OpenVMS usage itmlst_3 
type longword (unsigned) 

access read only 

mechanism by reference 

Item list specifying options for the routine. The injtemjist argument is the 
address of a list of item descriptors, each of which specifies an option and provides 
the information needed to perform the operation. 

The item list must include at least one device item descriptor. The item list is 
terminated by longword value of 0. 

Input Item Codes 

MAIL$_USER_CREATEJF 

The Boolean item code MAIL$_USER_CREATEJF specifies that MAIL$USER_ 
SET JNFO should create the record for the specified user if it does not already 
exist. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 
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MAIL$_USER_SET_AUTO_PURGE 

MAIL$_USER_SET_NO_AUTO_PURGE 

The Boolean item codes MAIL$_USER_SET_AUTO_PURGE and MAIL$_USER_ 
SET_NO_AUTO_PURGE set and clear the auto purge flag for the specifled user. 

Specify the value 0 in the buffer length and buffer address flelds of the item 
descriptor. 

MAIL$_USER_SET_CC_PROMPT 

MAIL$_USER_SET_NO_CC_PROMPT 

The Boolean item codes MAIL$_USER_SET_CC_PROMPT and MAIL$_USER_ 
SET_NO_CC_PROMPT set and clear the cc prompt flag for the specifled user. 

Specify the value 0 in the buffer length and buffer address flelds of the item 
descriptor. 

MAIL$_USER_SET_COPY_FORWARD 

MAIL$_USER_SET_NO_COPY_FORWARD 

The Boolean item codes MAIL$_USER_SET_COPY_FORWARD and MAIL$_ 
USER_SET_NO_COPY_FORWARD set and clear the copy self forward flag for 
the specifled user. 

Specify the value 0 in the buffer length and buffer address flelds of the item 
descriptor. 

MAIL$_USER_SET_COPY_REPLY 

MAIL$_USER_SET_NO_COPY_REPLY 

The Boolean item codes MAIL$_USER_SET_COPY_REPLY and MAIL$_USER_ 
SET_NO_COPY_REPLY set and clear the copy self reply flag for the specifled 
user. 

Specify the value 0 in the buffer length and buffer address flelds of the item 
descriptor. 

MAIL$_USER_SET_COPY_SEND 

MAIL$_USER_SET_NO_COPY_SEND 

The Boolean item codes MAIL$_USER_SET_COPY_SEND and MAIL$_USER_ 
SET_NO_COPY_SEND set and clear the copy self send flag for the specifled user. 

Specify the value 0 in the buffer length and buffer address flelds of the item 
descriptor. 

MAIL$_USER_SET_EDITOR 

MAIL$_USER_SET_NO_EDITOR 

MAIL$_USER_SET_EDITOR specifies the name of a default editor to be used by 
the specifled user. The buffer address fleld of the item descriptor points to a 
buffer that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length fleld of the item descriptor. 

The Boolean item code MAIL$_USER_SET_NO_EDITOR clears the default editor 
fleld for the specifled user. 

Specify the value 0 in the buffer length and buffer address flelds of the item 
descriptor. 
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MAIL$_USER_SET_FORM 

MAIL$_USER_SET_NO_FORM 

MAIL$_USER_SET_FORM specifies the default print form string for the specified 
user. The buffer address field of the item descriptor points to a buffer that 
contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

The Boolean item code MAIL$_USER_SET_NO_FORM clears the default print 
form field for the specified user. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

MAIL$_USER_SET_FORWARDING 

MAIL$_USER_SET_NO_FORWARDING 

MAIL$_USER_SET_FORWARDING specifies a forwarding address string for the 
specified user. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

The Boolean item code MAIL$_USER_SET_NO_FORWARDING clears the 
forwarding address field for the specified user. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

MAIL$_USER_SET_NEW_MESSAGES 

MAIL$_USER_SET_NEW_MESSAGES specifies the new message count for the 
specified user. The buffer address field of the item descriptor points to a word 
that contains the new number of new messages. 

MAIL$_USER_SET_PERSONAL_NAME 

MAIL$_USER_SET_NO_PERSONAL_NAME 

MAIL$_USER_SET_PERSONAL_NAME specifies a personal name string for the 
specified user. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

The Boolean item code MAIL$_USER_SET_NO_PERSONAL_NAME clears the 
personal field for the specified user. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

MAIL$_USER_SET_QUEUE 

MAIL$_USER_SET_NO_QUEUE 

MAIL$_USER_SET_QUEUE specifies a default print queue name string for the 
specified user. The buffer address field of the item descriptor points to a buffer 
that contains a character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

The Boolean item code MAIL$_USER_SET_NO_QUEUE clears the default print 
queue field for the specified user. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 
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MAIL$_USER_SET_SUB_DIRECTORY 

MAIL$_USER_SET_NO_SUB_DIRECTORY 

MAIL$_USER_SET_SUB_DIRECTORY specifies a MAIL subdirectory. The 
buffer address field of the item descriptor points to a buffer that contains a 
character string 0 to 255 characters long. 

Specify a value from 0 to 255 in the buffer length field of the item descriptor. 

The Boolean item code MAIL$_USER_SET_NO_SUB_DIRECTORY disables the 
use of a MAIL subdirectory for the specified user. 

Specify the value 0 in the buffer length and buffer address fields of the item 
descriptor. 

MAIL$_USER_USERNAME 

MAIL$_USER_USERNAME specifies the record to be modified in the user profile 
database and points to the username string. The buffer address field of the item 
descriptor points to a buffer that contains a character string 0 to 31 characters 
long. 

Specify a value from 0 to 31 in the buffer length field of the item descriptor. 

out_ltem_list 

OpenVMS usage itmlst_3 
type longword 

access write only 

mechanism by reference 

Item list specifying the information you want the routine to return. The out_ 
itemjist argument is the address of a list of item descriptors, each of which 
describes an item of information. The list of item descriptors is terminated by 
longword value of 0. 

Output Item Codes 

None. 


Description 

The MAIL$USER_SET_INFO routine modifies specified records in the user 
profile database. If you do not specify a user name, the routine modifies the user 
record associated with the calling process. 

To modify any user record other than that associated with the calling process, 
you must have SYSPRV privilege. However, if you want to add or modify only the 
forwarding address of another user, SYSNAM privilege is sufficient. 

Condition Values Returned 


SS$NORMAL 

MAIL$_CONITMCOD 

MAIL$_INVITMCOD 

MAIL$_INVITMLEN 


Normal successful completion. 

The specified item codes perform conflicting 
operations. 

The specified item code is invalid. 

The specified item length is invalid. 
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MAIL$_MISREQITEM The required item is missing. 

SS$_ACCVIO Access violation. 
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National Character Set (NCS) Utility Routines 


This chapter describes the National Character Set (NCS) utility routines. The 
NCS utility provides a common facility for defining and accessing collating 
sequences and conversion functions. Collating sequences are used to compare 
strings for sorting purposes. Conversion functions are used to derive an altered 
form of an input string based on an appropriate conversion algorithm. 

11.1 Introduction to NCS Routines 

Using NCS, you can formulate collating sequences and conversion functions and 
register them in an NCS library. The NCS routines provide a programming 
interface to NCS that lets you access the collating sequences and conversion 
functions from an NCS library for doing string comparisons. 

Typically, NCS collating sequences are selective subsets of the multinational 
character set. They are used extensively in programming applications involving 
various national character sets. For example, a program might use the Spanish 
collating sequence to assign appropriate collating weight to characters from the 
Spanish national character set. Another program might use the French collating 
sequence to assign appropriate collating weight to characters in the French 
national character set. 

In addition to providing program access to collating sequences and conversion 
functions in an NCS library, the NCS routines provide a means for saving 
definitions in a local file for subsequent use by the comparison and conversion 
routines. 

Table 11—1 lists the NCS routines. 


Table 11-1 NCS Routines 

Routine Description 


NCS$COMPARE 

NCS$CONVERT 

NCS$END_CS 

NCS$END_CF 

NCS$GET_CF 

NCS$GET_CS 


Compares two strings using specified collating sequence as 
comparison basis 

Converts a string using the specified conversion function 

Terminates the use of a collating sequence by the calling 
program 

Terminates the use of a conversion function by the calling 
program 

Retrieves the definition of the named conversion function 
from the NCS library 

Retrieves the definition of the named collating sequence from 
the NCS library 

(continued on next page) 
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Table 11-1 (Cent.) 

NCS Routines 

Routine 

Description 

NCS$RESTORE_CF 

Permits the calling program to restore the definition of a 
“saved” conversion function from a database or an RMS file 

NCS$RESTORE_CS 

Permits the calling program to restore the definition of a 
“saved” collating sequence from a database or an RMS file 

NCS$SAVE_CF 

Provides the calling program with information that permits 
the application to store the definition of a conversion function 
in a local database or an RMS file 

NCS$SAVE_CS 

Provides the calling program with information that permits 
the application to store the definition of a collating sequence 
in a local database or an RMS file 


In a typical application, the program does the following: 

1. Prepares a string for comparison 

2. Makes a call to the NCS$GET routine, specifying the appropriate collating 
sequence 

3. Makes one or more calls to the NCS$COMPARE routine, which does the 
actual comparison 

4. Terminates the comparison with a call to the NCS$END routine 

The program can also include the use of conversion functions in preparation for 
the comparison routines. 

11.2 Examples of How to Use NCS Utility Routines 

This section includes two examples of how to use NCS utility routines in program 
applications: 

Example 11-1 illustrates the use of NCS utility routines in a FORTRAN program. 


Example 11—2 illustrates the use of NCS routines in a C program. 

_ Note _ 

Each programming language provides an appropriate mechanism for 
defining symbols, status codes, completion codes, and other relevant 
information. 
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Example 11-1 Using NCS Routines in a FORTRAN Program 


PROGRAM NCS_EXAMPLE 

CHARACTER*80 CSSTRING,STRINGl,STRING2 

INTEGER*4 CSLENGTH,LENGTHl,LENGTH2,CSID,STATUS,RESULT 

INTEGER*4 NCS$GET_CS,NCS$COMPARE,NCS$END_CS 

CHARACTER*! CMP(3) 

CMP(l) = '<' 

CMP(2) = '=' 

CMP(3) = '>' 

C 

C Read the name of the collating sequence.. 

C 

WRITE (6,30) 

READ (5,15,END=999) CSLENGTH,CSSTRING 
30 FORMAT(' Collating Sequence: ') 

C 

C Get the collating sequence from the NCS library 

C 

CSID = 0 

STATUS = NCS$GET_CS (CSID, CSSTRING(1:CSLENGTH)) 

IF ((STATUS .AND. 1) .NE. 1) THEN 
CALL LIB$SIGNAL (%VAL(STATUS)) 

ENDIF 

C 

C Read two strings to be compared according to the collating sequence 

C 

100 WRITE (6,10) 

READ (5,15,END=999) LENGTHl,STRINGl 
WRITE (6,20) 

READ (5,15,END=999) LENGTH2,STRING2 

IF (LENGTHl .EQ. 0 .AND. LENGTH2 .EQ. 0) THEN 
GOTO 200 
ENDIF 

10 FORMAT(' Stringl: ') 

20 FORMAT(' String2: ') 

15 FORMAT (q,a80) 

C 

C Compare the strings 

C 

result = ncs$compare (csid, stringl(1:lengthl), string2(1:length2)) 
C 

C Display the results of the comparison 

C 

WRITE (6,40) STRING1(1:LENGTH1), CMP(RESULT+2), STRING2(1:LENGTH2) 
40 FORMAT(' ',A,' ',A,' ',A) 

GOTO 100 
C 

C Come here if both inputs are blanlc — we are done. 

C Call NCS$END_CS to free any storage used to hold the CS. 

C 

200 STATUS = NCS$END_CS (CSID) 

IF ((STATUS .AND. 1) .NE. 1) THEN 
CALL LIB$SIGNAL (%VAL(STATUS)) 

ENDIF 
CALL EXIT 

999 CONTINUE 

END 
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Example 11-2 Using NCS Routines in a C Program 


/* 


**-: 

** 

** NCS_EXAMPLE.C 
** 

** NCS conversion function example 
** 

using the VAX C programming language 

*/ 

/* 

* * 



** Header files 
*/ 

# include "sys$library:descrip.h" 

/* Descriptor macros */ 


# include "sys$library:rms.h" 

/* RMS structure definitions 

*/ 

# include "sys$libraryrrmsdef.h" 

/* RMS completion codes 

*/ 

# include "sys$share;ssdef.h" 

/* codes */ 

/* System service completion 

*/ 

# include "sys$library:stdio.h" 

/* 

** 

/* Standard I/O definitions 

*/ 


** Data definitions 
*/ 

tdefine SIZE 1024 /* Maximum record size */ 


unsigned long int 

cfid, /* Address of conversion */ 

/* function */ 

expected_status, /* Expected return status */ 

rms__status, /* RMS return status */ 

status; /* Function return status */ 

unsigned short int 

return_length; /* Length of returned string in */ 

/* bytes */ 


char 

file[NAM$C__MAXRSS], /* File name */ 

inrec[SIZE], /* Input record */ 

outrec[SIZE]; /* Output record */ 

$DESCRIPTOR(cfname_d,"EDT_VT2xx"); /* Conversion function name */ 

/* descriptor */ 

$DESCRIPTOR(prompt_d,"_File: "); /* Prompt string descriptor */ 

$DESCRIPTOR(file_d,file); /* File name descriptor */ 

$DESCRIPTOR(inrec_d,inrec); /* Input record descriptor */ 

$DESCRIPTOR(outrec_d,outrec); /* Output record descriptor */ 

struct FAB infab; /* Input file access block */ 

struct RAB inrab; /* Input record access block */ 

/* 

** _ 

** Function prototypes 
*/ 

void status_check(); 

/* 

** ============ = =:= ========:===== = ===== =========== = ===:======z ======== === ==== = 

*/ 

main () 

{ 


(continued on next page) 
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Example 11-2 (Cent.) Using NCS Routines in a C Program 

/* 

**_ 

** Initialize RMS user structures for the file. 

*/ 

infab = cc$rms_fab; /* Initialize to default FAB */ 

/* values */ 

infab.fab$l_fna = file; /* Now supply our specific */ 

/* values */ 

infab.fab$b_fns = NAM$C_MAXRSS; 

inrab = cc$rms_rab; /* Initialize to default RAB */ 

/* values */ 

inrab.rab$l_fab = &infab; /* Now supply our specific */ 

/* values */ 

inrab.rab$l_ubf = inrec; 
inrab.rab$w usz = SIZE; 

/* 

**_ 

** Get the EDT_VT2xx conversion function from the default NCS library 
*/ 

cfid =0; /* Initialize ID */ 

status = ncs$get_cf(&cfid,&cfname_d,0); 
status check(status,SS$ NORMAL); 

/* 

**_ 

** Get the file to be converted and set the length of the returned file 
** name 
*/ 

status = lib$get_input(&file_d,&prompt_d,&return_length); 
status_check(status,SS$_NORMAL); 
file_d.dsc$w_length = return_length; 

/* 

** _ 

** Open the input file to be converted and connect to the RAB 
*/ 

rms^status = sys$open(&infab,0,0); 
status^check(rms_status,RMS$_NORMAL); 

rms_status = sys$connect(&inrab,0,0); 
status check(rms status,RMS$ NORMAL); 

/* 

**_ 

** Read each record from the file, convert the input string to EDT 
** fallback, and write the result to the output 
*/ 

while(TRUE) 

{ 


** Read each record 
*/ 

rms_status = sys$get(&inrab,0,0); 

if (rms_status == RMS$_EOF) /* Reached end of file */ 

break; 

else 

status_check(rms_status,RMS$_NORMAL); /* Read a record */ 


(continued on next page) 
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Example 11-2 (Cont.) Using NCS Routines in a C Program 

/* 

"k -k _____________________________________________________________ 

** Call NCS$CONVERT to convert the input string to EDT fallback 

kk 

** e.g. Convert form feed to <FF>, escape to <ESC>, et cetera 
*/ 

inrec__d.dsc$w_length = inrab.rab$w_rsz; 

status = ncs$convert(&cfid,&inrec__d,&outrec_d,&return__length); 
status_check(status,SS$__NORMAL); 
outrec d.dsc$w length = return_length; 

/* 

kk _ 

** Write the result to the output, SYS$OUTPUT in this case 
*/ 

status = lib$put_output(&outrec_d); 
status_check(status,SS$_NORMAL); 
outrec_d.dsc$w_length = SIZE; 

} 

/* 

kk _ 

** Close the input file. 

*/ 

rms__status = sys$close(&infab,0,0); 
status check(rms status,RMS$ NORMAL); 

/* ““ 

kk _ 

** Free any storage used to hold the conversion function. 

*/ 

status = ncs$end__cf (&cfid); 
status_check(status,SS$_N0RMAL); 


void status_check(status,expected_status) 

/* 

kk ===== === = = = = = =:=======: = = = = ===== ==== =====:==: ====z============ = =====:= = ===:=:=====; 

k k 

** Checks the function return status against the one expected, and exits upon 
** error. Otherwise, return to the main program. 

kk 

kk = ====== = z= ===z=z====:==zzz==z==== = = = ===============;==z==:=====:========:=:===:==:==:=====: 

*/ 

{ 

if (status != expected_status) 
sys$exit(status); 

else 

return; 

} 


11.3 NCS Routines 

The following pages describe the NCS routines. 
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NCS$COMPARE 


NCS$COMPARE—Compare Strings 

The NCS$COMPARE routine compares two strings using a specified collating 
sequence as a comparison basis. 


Format 

NCS$COMPARE csjd ,string_1 ,string_2 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


integer 

longword integer (signed) 
write only 
by value 


Longword condition value. Most routines return a condition value in RO but the 
NCS$COMPARE routine uses RO to return the result of the comparison, as shown 
in the following table: 


Returned Value 

Comparison Result 

-1 

string_l is less than string_2 

0 

string__l is equal to string_2 

1 

string_l is greater than string_2 


The NCS$COMPARE routine uses the Signaling Mechanism to indicate 
completion status as described under CONDITION VALUE SIGNALED. 


Arguments 

cs_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access read only 

mechanism by reference 

Address of a longword that NCS uses to identify a collating sequence. The cs_id 
argument is required and can be obtained by a call to the NCS$GET_CS routine. 

All calls to the NCS$COMPARE routine and the call to the NCS$END_CS 
routine that terminates the comparison must pass this longword identifier. Upon 
completion, the NCS$END_CS routine releases the memory used to store the 
collating sequence and sets the value of the longword identifier to zero. 

string_1 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Descriptor (length and address) of the first string. 
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string_2 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Descriptor of the second string. 


Description 

The NCS$COMPARE routine compares two strings using the specified collating 
sequence as the comparison basis. The routine indicates whether the value of the 
first string is greater than, less than, or equal to the value of the second string. 

Condition Value Signaled 

STR$_ILLSTRCLA Illegal string class. Severe error. The descriptor 

of string_l or string_2, or both, contains a class 
code not supported by the OpenVMS Calling 
Standard. 
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NCS$CONVERT—Convert String 

The NCS$CONVERT routine converts a string using the specified conversion 
function. 


Format 


NCSSCONVERT cfjd ,source ,dest [,retjength] [,not_cvt] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

cf_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access read only 

mechanism by reference 

Address of a longword that NCS uses to identify a conversion function. The cf_id 
argument is required and can be obtained by a call to the NCS$GET_CF routine. 

All calls to the NCS$CONVERT routine and the call to the NCS$END_CF 
routine that terminates the conversion must pass this longword identifier. Upon 
completion, the NCS$END_CF routine releases the memory used to store the 
conversion function and sets the value of the longword identifier to zero. 

source 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Descriptor of source string. 

dest 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Descriptor of destination string. 
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ret_length 

OpenVMS usage word unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Length of converted string. 

not_cvt 

OpenVMS usage word unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of characters in the source string that were not fully converted. 

Description 

Using the specified conversion function, the NCS$CONVERT routine converts the 
source string and stores the result in the specified destination. Optionally, the 
calling program can request that the routine return the length of the converted 
string as well as the number of characters which were not fully converted. 

Condition Values Returned 

NCS$_NOT_CF Name of identifier does not refer to a conversion 

function. 

SS$_NORMAL Successful completion. 

STR$_TRU Successful completion. However, the resultant 

string was truncated because the storage 
allocation for the destination string was 
inadequate. 

Condition Values Signaled 

LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 

Any value signaled by STR$COPY_DX or STR$ANALYZE_SDESC. 
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NCS$END_CF—End Conversion Function 

The NCS$END_CF routine terminates a conversion function. 

Format 

NCS$END_CF cfjd 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

cf_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access modify 

mechanism by reference 

Address of a longword that NCS uses to store a nonzero value identifying a 
conversion function. 

The cf_id argument is required. 

Description 

The NCS$END_CF routine indicates to NCS that the calling program no longer 
needs the conversion function. NCS releases the memory space allocated for the 
coversion function and sets the value of the longword identifier to zero. 

Condition Values Returned 

NCS$_NORMAL Normal successful completion. The longword 

identifier value is set to zero. 

NCS$_NOT_CF Name of identifier does not refer to a conversion 

function. 
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NCS$END_CS—End Collating Sequence 

The NCS$END_CS routine terminates a collating sequence. 

Format 

NCS$END_CS csjd 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Argument 

cs_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access modify 

mechanism by reference 

Address of a longword that NCS uses to store a nonzero value identifying a 
collating sequence. 

The cs_id argument is required. 

Description 

The NCS$END_CS routine indicates to NCS that the calling program no longer 
needs the collating sequence. NCS releases the memory space allocated for the 
collating sequence and sets the value of the longword identifier to zero. 

Condition Values Returned 

NCS$_NORMAL Normal successful completion. The longword 

identifier value is set to zero. 

NCS$_NOT_CS Name of identifier does not refer to a collating 

sequence. 
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NCS$GET_CF—Get Conversion Function 

The NCS$GET_CF routine retrieves the definition of the named conversion 
function from the NCS library. 


Format 

NCS$GET_CF cfjd [,cfname] [Jibrar] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

cf_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access modify 

mechanism by reference 

Address of a longword used by NCS to identify a conversion function. The 
calling program must ensure that the longword contains zero before invoking 
the NCS$GET_CF routine because the routine stores a nonzero value in the 
longword. The nonzero value identifies the conversion function. All subsequent 
calls to the NCS$CONVERT routine and the call to the NCS$END_CF routine to 
terminate the conversion function pass the longword identifier. When it completes 
the conversion, the NCS$END_CF routine releases the memory used to store the 
conversion function and sets the value of the longword identifier to zero. 

The conversion function identifier enhances modular programming and permits 
concurrent use of multiple conversion functions within a program. 

The calling program should not attempt to interpret the contents of the longword 
identifier. 

The cf_id argument is required. 

cfname 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the conversion function being retrieved. 
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librar 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the library where the conversion function is stored. 


Description 

The NCS$GET_CF routine extracts the named conversion function from the 
specified NCS library. 

If the calling program omits the cfname argument, an “identity” conversion 
function padded with NUL characters (hex 0) is provided. The identity conversion 
function effectively leaves each character unchanged by converting each character 
to itself. For example, A becomes A, B becomes B, C becomes C, and so forth. 

If the calling program omits the librar argument, NCS accesses the default NCS 
library. 

Condition Values Returned 

NCS$_DIAG 
NCS$_NOT_CF 

NCS$_NOT_FOUND 

Condition Values Signaled 

LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 


Operation completed with signaled diagnostics. 

Name of identifier does not refer to a conversion 
function. 

Name of identifier not found in the NCS library. 
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NCS$GET_CS—Get Collating Sequence 

The NCS$GET_CS routine retrieves the definition of the named collating 
sequence from the NCS library. 


Format 

NCS$GET_CS csjd [,csname] [Jibrar] 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

cs_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access modify 

mechanism by reference 

Address of a longword that NCS uses to store a nonzero value identifying a 
collating sequence. The calling program must ensure that the longword identifier 
contains zero before invoking the NCS$GET_CS routine. 

All subsequent calls to the NCS$COMPARE routine and the call to the 
NCS$END_CS routine that terminates the use of the collating sequence 
must pass this longword identifier. Upon completion of the comparisons, the 
NCS$END_CS routine releases the memory used to store the collating sequence 
and sets the value of the longword identifier to zero. 

The collating sequence identifier enhances modular programming and permits 
concurrent use of multiple collating sequences within a program. 

The calling program should not attempt to interpret the contents of the longword 
identifier. 

The cs__id argument is required. 

csname 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the collating sequence being retrieved. 

librar 

OpenVMS usage char_string 
type character string 

access read only 
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mechanism by descriptor 

File specification of the library where the collating sequence is stored. 


Description 

The NCS$GET_CS routine extracts the named collating sequence from the 
specified NCS library. If the calling program omits the csname argument, NCS 
creates a collating sequence that uses the “native” collating sequence as a basis 
for the comparisons. This collating sequence is padded with NUL characters (hex 
0 ). 

If the calling program omits the librar argument, NCS accesses the default NCS 
library. 

Condition Values Returned 

NCS$_DIAG 
NCS$_NOT_CS 

NCS$_NOT_FOUND 

Condition Values Signaled 

LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 


Operation completed with signaled diagnostics. 

Name of identifier does not refer to a collating 
sequence. 

Name of identifier not found in the NCS library. 
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NCS$RESTORE_CF—Restore Conversion Function 

The NCS$RESTORE_CF routine permits the calling program to restore the 
definition of a saved conversion function from a database or a file. 


Format 

NCS$RESTORE_CF cfjd [,length] [,address] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under CONDITION 
VALUE RETURNED. 


Arguments 

cf_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access write only 

mechanism by reference 

Address of a longword that NCS uses to identify a conversion function. 

The cf_id argument is required. 

length 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Longword that the calling program uses to indicate the length of the conversion 
function being restored. 

address 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Longword that the calling program uses as a pointer to the conversion function 
being restored. 
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Description 

The NCS$RESTORE_CF routine, used in conjunction with the NCS$SAVE_CF 
routine, permits the application program to keep a local copy of the conversion 
function. The NCS$SAVE_CF routine obtains the length and location of the 
conversion function and returns it to the application program. The application 
program subsequently provides this information to the NCS$RESTORE_CF 
routine, which uses it to access the conversion function. 

This routine also does some integrity checking on the conversion function as it is 
being processed. 

Condition Value Returned 

NCS$_NOT_CF Name of identifier does not refer to a conversion 

function. 

Condition Values Signaled 

LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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NCS$RESTORE_CS—Restore Collating Sequence 

The NCS$RESTORE_CS routine permits the calling program to restore the 
definition of a “saved” collating sequence from a database or a file. 


Format 


Returns 


NCS$RESTORE_CS csjd [,length] [,address] 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under CONDITION 
VALUE RETURNED. 


Arguments 

cs_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access write only 

mechanism by reference 

Address of a longword that NCS uses to identify a collating sequence. 

The cs_id argument is required. 

length 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Longword that the calling program uses to indicate the length of the collating 
sequence being restored. 

address 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Longword that the calling program uses as a pointer to the collating sequence 
being restored. 
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Description 

The NCS$RESTORE_CS routine, used in conjunction with the NCS$SAVE_CS 
routine, permits the application program to keep a local copy of the collating 
sequence. The NCS$SAVE_CS routine obtains the length and location of the 
collating sequence and returns it to the application program. The application 
program subsequently provides this information to the NCS$RESTORE_CS 
routine, which uses it to access the collating sequence. 

This routine also does some integrity checking on the collating sequence as it is 
being processed. 

Condition Value Returned 

NCS$_NOT_CS Name of identifier does not refer to a collating 

sequence. 

Condition Values Signaled 

LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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NCS$SAVE_CF—Save Conversion Function 

The NCS$SAVE_CF routine provides the calling program with information that 
permits the application to store the definition of a conversion function in a local 
database or a file rather than in the NCS library. 


Format 

NCS$SAVE_CF cfjd [,length] [,address] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under CONDITION 
VALUE RETURNED. 


Arguments 

cf_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access read only 

mechanism by reference 

Address of a longword that NCS uses to identify a conversion function. 
The cf_id argument is required. 

length 

OpenVMS usage 
type 
access 
mechanism 

Longword used to 

address 

OpenVMS usage 
type 
access 
mechanism 

Longword used to 


longword_unsigned 
longword (unsigned) 
write only 
by reference 

store the length of the specified conversion function. 

longword_unsigned 
longword (unsigned) 
write only 
by reference 

store the address of the specified conversion function. 


Description 

The NCS$SAVE_CF routine, used in conjunction with the NCS$_RESTORE_CF 
routine, permits the application program to store a conversion function definition 
in a local file or in a database. When the calling program specifies the conversion 
function identifier, NCS returns the location of the definition and its length in 
bytes, permitting the calling program to store the definition locally, rather than 
in an NCS library. Subsequently, the application supplies this information to the 
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NCS$RESTORE_CF routine, which restores the conversion function to a form 
that can be used by the NCS$CONVERT routine. 

This routine also does some integrity checking on the conversion function as it is 
being processed. 

Condition Value Returned 

NCS$_NOT_CF Name of identifier does not refer to a conversion 

function. 

Condition Values Signaled 

LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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NCS$SAVE_CS—Save Collating Sequence 

The NCS$SAVE_CS routine provides the calling program with information that 
permits the application program to store the definition of a collating sequence in 
a database or a file rather than in the NCS library. 


Format 


NCS$SAVE_CS csjd [.length] [.address] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under CONDITION 
VALUE RETURNED. 


Arguments 

cs_id 

OpenVMS usage identifier 
type longword integer (unsigned) 

access read only 

mechanism by reference 

Address of a longword that NCS uses to identify a collating sequence. 

The cs_id argument is required. 

length 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Longword that NCS uses to indicate the length of the specified collating sequence 
to the calling program. 

address 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Longword that NCS uses to indicate the address of the specified collating 
sequence to the calling program. 
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Description 

The NCS$SAVE_CS routine, used in conjunction with the NCS$_RESTORE_CS 
routine, permits the application program to store a collating sequence definition 
in a local file or in a database. When the calling program specifies the collating 
sequence identifier, NCS returns the location of the definition sequence and its 
length in bytes, permitting the calling program to store the definition locally, 
rather than in a library. Subsequently, the application supplies this information 
to the NCS$RESTORE_CS routine, which restores the collating sequence to a 
form that can be used by the NCS$COMPARE routine. 

This routine also does some integrity checking on the collating sequence as it is 
being processed. 

Condition Value Returned 

NCS$_NOT_CS Name of identifier does not refer to a collating 

sequence. 

Condition Values Signaled 

LBR messages (prefaced by an NCS message) might signal errors detected while 
the process is accessing the NCS library. 
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The print symbiont modification (PSM) routines allow you to modify the behavior 
of the print symbiont supplied with the operating system. 

12.1 Introduction to PSM Routines 

The print symbiont processes data for output to standard line printers and 
printing terminals by performing the following functions: 

• Reading the data from disk 

• Formatting the data 

• Sending the data to the printing device 

• Composing separation pages (fiag, burst, and trailer pages) and inserting 
them into the data stream for printing 

Some of the reasons for modifying the print symbiont include the following: 

• To include additional information on the separation pages (fiag, burst, and 
trailer) or to format them differently 

• To filter and modify the data stream sent to the printer 

• To change some of the ways that the symbiont controls the printing device 

You might not always be able to modify the print symbiont to suit your needs. 

For example, you cannot do the following: 

• Modify the symbionFs control logic or the sequence in which the symbiont 
calls routines 

• Modify the interface between the symbiont and the job controller 

If you cannot modify the print symbiont to suit your needs, you might want to 
write your own symbiont. Section 12.3 describes how to write your own symbiont 
and integrate it with the operating system. However, you should modify the print 
symbiont, when possible, rather than write your own symbiont. 

The rest of this chapter contains the following information about PSM routines: 

• Section 12.2 contains an overview of the print symbiont and of symbionts 
in general. It explains concepts such as “symbiont streams”; describes the 
relationship between a symbiont, a device driver, and the job controller; and 
gives an overview of the print symbiont’s internal logic. 

This section is recommended for those who want to either modify the print 
symbiont or write a new symbiont. 

• Section 12.3 details the procedure for modifying the print symbiont. 

It includes an overview of the entire procedure, followed by a detailed 
description of each step. 
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• Section 12.4 contains an example of a simple modification to the print 
symbiont. 

• Section 12.5 describes each PSM routine and the interface used by the 
routines you substitute for the standard PSM routines. 

12.2 Print Symbiont Overview 

The operating system supplies two symbionts: a print symbiont, which is an 
output symbiont, and a card reader, which is an input symbiont. An output 
symbiont receives tasks from the job controller, whereas an input symbiont sends 
jobs to the job controller. The card reader symbiont cannot be modified. You can 
modify the print symbiont, described in this section, using PSM routines. 

There are two types of output symbiont: device and server. A device symbiont 
processes data for output to a device, for example, a printer. A server symbiont 
also processes data but not necessarily for output to a device, for example, a 
symbiont that copies files across a network. The operating system supplies no 
server symbionts. 

12.2.1 Components of the Print Symbiont 

The print symbiont includes the following major components: 

• PSM routines that are used to modify the print symbiont 

• Routines that implement input, format, and output services in the print 
symbiont 

• Routines that implement the internal logic of the print symbiont 

The print symbiont is implemented using the Symbiont Services Facility. This 
facility provides communication and control between the job controller and 
symbionts through a set of Symbiont/Job Controller Interface Routines (SMB 
routines), which are documented in Chapter 13. 

All of these routines are contained in a shareable image with the file specification 
SYS$SHARE:SMBSRVSHR.EXE. 

12.2.2 Creation of the Print Symbiont Process 

The print symbiont is a device symbiont, receiving tasks from the job controller 
and processing them for output to a printing device. In the operating system, 
the existence of a print symbiont process is linked to the existence of at least one 
print execution queue that is started. 

The job controller creates the print symbiont process by calling the Create 
Process ($CREPRC) system service; it does this whenever either of the following 
conditions occur: 

• A print execution queue is started (from the stopped state) and no symbiont 
process is running the image specified with the START/QUEUE command. 

A print execution queue is started by means of the DCL command START 
/QUEUE. You can use the /PROCESSOR qualifier with the START/QUEUE 
command to specify the name of the symbiont image that is to service an 
execution queue; if you omit /PROCESSOR, then the default symbiont image 
is PRTSMB. 
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• Currently existing symbiont processes suited to a print execution queue 
cannot accept additional devices; that is, the symbionts have no more 
available streams. In such a case, the job controller creates another print 
symbiont process. The next section discusses symbiont streams. 

The print symbiont process runs as a detached process. 

12.2.3 Symbiont Streams 

A stream is a logical link between a print execution queue and a printing device. 
When the queue is started (by means of START/QUEUE), the job controller 
creates a stream linking the queue with a symbiont process. Because each 
print execution queue has a single associated printing device (specified with 
the /ON=device_name qualifier in the INITIALIZE/QUEUE or START/QUEUE 
command), each stream created by the job controller links a print execution 
queue, a symbiont process, and the queue’s associated printer. 

A symbiont that can support multiple streams simultaneously (that is, multiple 
print execution queues and multiple devices) is termed a multithreaded symbiont. 
The job controller enforces an upper limit of 16 on the number of streams that 
any symbiont can service simultaneously. 

Therefore, in the operating system environment, only one print symbiont process 
is needed as long as the number of print execution queues (and associated 
printers) does not exceed 16. If there are more than 16 print execution queues, 
the job controller creates another print symbiont process. 

The print symbiont is, therefore, a multithreaded symbiont that can service as 
many as 16 queues and devices, but you can modify it to service any number of 
queues and devices as long as the number is less than or equal to 16. 

A symbiont stream is said to be “active” when a queue is started on that stream. 
The print symbiont maintains a count of active streams. It increments this count 
each time a queue is started and decrements it when a queue is stopped with the 
DCL command STOP/QUEUE/NEXT or STOP/QUEUE/RESET. When the count 
falls to zero, the symbiont process exits. The symbiont does not decrement the 
count when the queue is paused by STOP/QUEUE. 

Figure 12-1 shows the relationship of generic print queues, execution print 
queues, the job controller, the print symbiont, printer device drivers, and printers. 
The lines connecting the boxes denote streams. 
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Figure 12-1 Multithreaded Symbiont 
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12.2.4 Symbiont and Job Controller Functions 

This section compares the roles of the symbiont and job controller in the execution 
of print requests. You issue print requests using the PRINT command. 

The job controller uses the information specified on the PRINT command line to 
determine the following: 

• Which queue to place the job in (/QUEUE, /REMOTE, /LOWERCASE, and 
/DEVICE) 

• How many copies to print (/COPIES and /JOB_COUNT) 

• Scheduling constraints for the job (/PRIORITY, /AFTER, /BLOCK_LIMIT, 
/HOLD, /FORM, /CHARACTERISTICS, and /RESTART) 

• How and whether to display the status of jobs and queues (/NOTIFY, 
/OPERATOR, and /IDENTIFY) 

The print symbiont, on the other hand, interprets the information supplied with 
the qualifiers that specify this information: 

• Whether to print file separation pages (/BURST, /FLAG, and /TRAILER) 

• Information to include when printing the separation pages (/NAME and 
/NOTE) 

• Which pages to print (/PAGES) 

• How to format the print job (/FEED, /SPACE, and /PASSALL) 

• How to set up the job (/SETUP) 

The print symbiont, not the job controller, performs all necessary device-related 
functions. It communicates with the printing device driver. For example, when a 
print execution queue is started (by means of START/QUEUE/ON=device_name) 
and the stream is established between the queue and the symbiont, the symbiont 
parses the device name specified by the /ON qualifier in the START/QUEUE 
command, allocates the device, assigns a channel to it, obtains the device 
characteristics, and determines the device class. In versions of the operating 
system prior to Version 4.0, the job controller performed these functions. 

The print symbiont’s output routine returns an error to the job controller if the 
device class is neither printer nor terminal. 
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12.2.5 Print Symbiont Internal Logic 

The job controller deals with units of work called jobs, while the print symbiont 
deals with units of work called tasks. A print job can consist of several print 
tasks. Thus, in the processing of a print job, the job controller’s role is to divide 
a print job into one or more print tasks, which the symbiont can process. The 
symbiont reports the completion of each task to the job controller, but the 
symbiont contains no logic to determine that the print job as a whole is complete. 


In the processing of a print task, the symbiont performs three basic functions: 
input, format, and output. The symbiont performs these functions by calling 
routines to perform each function. 

The following steps describe the action taken by the symbiont in processing a 
task: 

1. The symbiont receives the print request from the job controller and stores it 
in a message buffer. 

2. The symbiont searches its list of input routines and selects the first input 
routine that is applicable to the print task. 

3. The input routine returns a data record to the symbiont’s input buffer or in a 
buffer supplied by the input routine. 

4. Data in the input buffer is moved to the symbiont’s output buffer by the 
formatting routines, which format it in the process. 

5. Data in the output buffer is sent to the printing device by the output routine. 

6. When an input routine completes execution, that is, when it has no more 
input data to process, the symbiont selects another applicable input routine. 
Steps 3, 4, and 5 are repeated until all applicable input routines have 
executed. 

7. The symbiont informs the job controller that the task is complete. 

Figure 12—2 illustrates the steps taken by the symbiont in the processing of a 
print task. 
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Figure 12-2 Symbiont Execution Sequence or Flow of Control 


Input 

Routines 
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As Figure 12-2 shows, most of the input routines execute in a specified sequence. 
This sequence is defined by the symbiont’s main control routine. You cannot 
modify this main control routine; thus, you cannot modify the sequence in which 
symbiont routines are called. 

The input routines that do not execute in sequence are called “demand input 
routines.” These routines are called whenever the service they provide is required 
and include the page header, page setup, and library module input routines. 

The symbiont can perform input, formatting, and output functions 
asynchronously; that is, the order in which the symbiont calls the input, 
formatting, and output routines can vary. For example, the symbiont can 
call an input routine, which returns a record to the input buffer; it can then call 
the format routine, which moves that record to the output buffer; and then it can 
call the output routine to move that data to the printing device. This sequence 
results in the movement of a single data record from disk to printing device. 

On the other hand, the symbiont can call the input and formatting routines 
several times before calling the output routine for a single buffer. The buffer 
can contain one or more formatted input records. In some cases an output buffer 
might contain only a portion of an input record. 

In this way the symbiont can buffer input records; then call the format routine, 
which moves one of those records to the output buffer; and finally call the output 
routine, which moves that data to the printing device. Note, however, that the 
formatting routine must be called once for each input record. 

Similarly, the symbiont can buffer several formatted records before calling the 
output routine to move them to the printing device. 

The symbiont requires this flexibility in altering the sequence in which input, 
format, and output routines are called for reasons of efficiency (high rate of 
throughput) and adaptability to various system parameters and system events. 
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The value specified with the call to PSM$PRINT determines the maximum size of 
the symbiont’s output buffer, which cannot be larger than the value of the system 
parameter MAXBUF. If the buffer is very small, the symbiont might need to call 
its output routine one or more times for each record formatted. If the buffer is 
large, the symbiont will buffer several formatted records before calling the output 
routine to move them to the printing device. 

12.3 Symbiont Modification Procedure 

To modify the print symbiont, perform the following steps. These steps are 
described in more detail in the sections that follow. 

1. Determine the modification needed. The modification might involve changing 
the way the symbiont performs a certain function, or it might involve adding 
a new function. 

2. Determine where to make the modification. This involves selecting a function 
and determining where that function is performed within the symbiont’s 
execution sequence. You specify a function by calling the PSM$REPLACE 
routine and specifying the code that identifies the function. 

Some codes correspond to symbiont-supplied routines. When you specify one 
of these codes, you replace that routine with your routine. Other codes do 
not correspond to symbiont-supplied routines. When you specify one of these 
codes, you add your routine to the set of routines the symbiont executes. 
Table 12-1 lists these codes. 

3. Write the routine. Because the symbiont calls your routine, your routine must 
have one of three call interfaces, depending on whether it is an input, format, 
or output routine. See the descriptions of the USER-INPUT-ROUTINE, 
USER-FORMAT-ROUTINE, and USER-OUTPUT-ROUTINE routines, which 
follow the descriptions of the PSM routines. 

4. Write the symbiont-initialization routine. This routine executes when the 
symbiont is first activated by the job controller. It initializes the symbiont’s 
internal database; specifies, by calling PSM$REPLACE, the routines you have 
supplied; activates the symbiont by calling PSM$PRINT; and performs any 
necessary cleanup operations when PSM$PRINT completes. 

5. Construct the modified symbiont. This involves compiling your routines, then 
linking them. 

6. Integrate the modified symbiont with the system. This involves placing the 
executable image in SYS$SYSTEM, identifying the symbiont image to the job 
controller, and debugging the symbiont. 

As mentioned previously, you identify each routine you write for the symbiont 
by calling the PSM$REPLACE routine. The code argument for this routine 
specifies the point within the symbiont’s execution sequence at which you want 
your routine to execute. You should know which code you will use to identify 
your routine before you begin to write the routine. Section 12.3.6 provides more 
information about these codes. 
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12.3.1 Guidelines and Restrictions 

The following guidelines and restrictions apply to the writing of any symbiont 
routine: 

• Do not use the process-permanent files identified by the logical names 
SYS$INPUT, SYS$OUTPUT, SYS$ERROR, and SYS$COMMAND. 

• The symbiont code should be linked against SMBSRVSHR.EXE in order to 
define the following status codes: 

- PSM$_FLUSH 

- PSM$_FUNNOTSUP 

- PSM$_PENDING 

- PSM$_SUSPEND 

- PSM$_EOF 

- PSM$_BUFFEROVF 

- PSM$_NEWPAGE 

- PSM$_ESCAPE 

- PSM$_INVVMSOSC 

- PSM$_MODNOTFND 

- PSM$_NOFILEID 

- PSM$_OSCTOOLON 

- PSM$_TOOMANYLEV 

- PSM$_INVITMCOD 

• Do not use the system services SYS$HIBER and SYS$WAKE. 

• Use the following two Run-Time-Library routines for allocation and 
deallocation of memory: LIB$GET_VM and LIB$FREE_VM. 

• Minimize the amount of time that your routine spends executing at AST level. 
The job controller sends messages to the symbiont by means of user-mode 
ASTs; the symbiont cannot receive these ASTs while your user routine is 
executing at AST level. 

• The symbiont can call your routines at either AST level or non-AST level. 

• If your routine returns any error-condition value (low bit clear), the symbiont 
aborts the current task and notifies the job controller. Note that, by default, 
an error-condition value returned during the processing of a task causes 
the job controller to abort the entire job. However, this default behavior 
can be overridden. See the description of the /RETAIN qualifier of the DCL 
commands START/QUEUE, INITIALIZE/QUEUE, and SET QUEUE in the 
OpenVMS DCL Dictionary. 

The symbiont stores the first error-condition value (low bit clear) returned 
during the processing of a task. The symbiont’s file-errors routine, an input 
routine (code PSM$K_FILE_ERRORS), places the message text associated 
with this condition value in the symbiont’s input stream. The symbiont prints 
this text at the end of the listing, immediately before the trailer pages. 
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The symbiont sends this error-condition value to the job controller; the job 
controller then stores this condition value with the job record in the job 
controller’s queue file. The job controller also writes this condition value in 
the accounting record for the job. 

If you choose to return a condition value when an error occurs, you should 
choose one from the system message file. This lets system programs access 
the message text associated with the condition value. Specifically, the 
Accounting and SHOW/QUEUE utilities and the job controller will be able to 
translate the condition value to its corresponding message text and to display 
this message text as appropriate. 

This guideline applies to input, input-filter, and output-filter routines, and to 
the symbiont’s use of dynamic string descriptors in these routines. 

The simplest way for an input routine to pass the data record to the symbiont 
is for it to use an RTL string-handling routine (for example, STR$COPY_R). 
These routines use dynamic string descriptors to point to the record they have 
handled to copy the record from your input buffer to the symbiont-supplied 
buffer specified in the funcdesc argument to the input routine. 

By default, the symbiont initializes a dynamic string descriptor that your 
input routine can use to describe the data record it returns. Specifically, the 
symbiont initializes the DSC$B_DTYPE field of the string descriptor with 
the value DSC$K_DTYPE_T (which indicates that the data to which the 
descriptor points is a string of characters) and initializes the DSC$B_CLASS 
field with the value DSC$K_CLASS_D (which indicates that the descriptor is 
dynamic). 

Alternatively, the input routine can pass a data record to the symbiont by 
providing its own buffer and passing a static string descriptor that describes 
the buffer. To do this, you must redefine, using the following steps, the fields 
of the descriptor to which the funcdesc argument points: 

1. Initialize the field DSC$B_CLASS with the value DSC$K_CLASS_ 

S (which indicates that the descriptor points to a scalar value or a 
fixed-length string). 

2. Initialize the field DSC$A_POINTER with the address of the buffer that 
contains the data record. 

3. Initialize the field DSC$W_LENGTH with the length, in bytes, of the data 
record. 

Each time the symbiont calls the routine to read some data, the symbiont 
reinitializes the descriptor to make it a dynamic descriptor. Consequently, 
if you want to use the descriptor as a static descriptor, your input routine 
must initialize the descriptor as described previously every time it is called to 
perform a reading operation. 

Input-filter routines and output-filter routines return a data record to the 
symbiont by means of the func_desc_2 argument. The symbiont initializes 
a descriptor for this argument the same way it does for descriptors used by 
input routine described previously. Thus, the guidelines described for the 
input routine apply to the input-filter routine and output-filter routine. 
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12.3.2 Writing an input Routine 

This section provides an overview of the logic used in the print symbiont’s main 
input routine, and it discusses the way in which the print symbiont handles 
carriage-control effectors. 

The print symbiont calls your input routine, supplying it with arguments. Your 
. routine must return arguments and condition values to the print symbiont. For 
this reason, your input routine must use the interface described in the description 
of the USER-INPUT-ROUTINE. 

When the print symbiont calls your routine, it specifies a particular request in 
the func argument. Each function has a corresponding code. 

Your routine must provide the functions identified by the codes PSM$K_OPEN, 
PSM$K_READ, and PSM$K_CLOSE. Your routine need not respond to the other 
function codes, but it can if you want it to. If your routine does not provide a 
function that the symbiont requests, it must return the condition value PSM$_ 
FUNNOTSUP to the symbiont. 

The description of the func argument of the USER-INPUT-ROUTINE describes 
the codes that the symbiont can send to an input routine. 

See Section 12.3.5 for additional information about other function codes used in 
the user-written input routine. 

For each task that the symbiont processes, it calls some input routines only once, 
and some more than once; it always calls some routines and calls others only 
when needed. 

Table 12—1 lists the codes that you can specify when you call the PSM$REPLACE 
routine to identify your input routine to the symbiont. The description of the 
PSM$REPLACE routine describes these routines. 

12.3.2.1 Internal Logic of the Symbiont’s Main Input Routine 

The internal logic of the symbiont’s main input routine, as described in this 
section, is subject to change without notice. This logic is summarized here. This 
summary is not intended as a tutorial on the writing of a symbiont’s main input 
routine, although it does provide insight into such a task. 

A main input routine is one that the symbiont calls to read data from the file that 
is to be printed. A main input routine must perform three sets of tasks: one set 
when the symbiont calls the routine with an OPEN request, one set when the 
symbiont calls with a READ request, and one set when the symbiont calls with a 
CLOSE request. 

The following table names the codes that identify each of these three requests 
and describes the tasks that the symbiont’s main input routine performs for each 
of these requests. 
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Code Action Taken by the Input Routine 

PSM$K_OPEN An OPEN request. When the main input routine receives this 

request code, it does the following: 

1. Opens the input file. 

2. Stores information about the input file. 

3. Returns the type of carriage control used in the input file. If 
this routine cannot open the file, it returns an error. 

Note that the print symbiont’s main input routine performs these 
tasks when it receives the PSM$K_START_TASK function code, 
rather than the PSM$K_OPEN function code. 

This atypical behavior occurs because some of the information 
stored by the main input routine must be available for other input 
routines that execute before the main input routine. For example, 
information about file attributes and record formats is needed 
by the symbiont’s separation-page routines, which print flag and 
burst pages. 

Consequently, if you supply your own main input routine, some 
of the information about the file being printed that appears on 
the standard separation pages is not available, and the symbiont 
prints a message on the separation page stating so. 

The symbiont receives the file-identification number from the job 
controller in the SMBMSG$K_FILE_IDENTIFICATION item of 
the requesting message and uses this value rather than the file 
specification to open the main input file. 

PSM$K_READ A READ request. When the main input routine receives this 

request, it returns the next record from the file. In addition, when 
the carriage control used by the data file is PSM$K_CC_PRINT, 
the main input routine returns the associated record header. 

PSM$K_CLOSE A CLOSE request. When the main input routine receives this 

request, it closes the input file. 


12.3.2.2 Symbiont Processing of Carriage Control 

Each input record can be thought of as consisting of three parts: leading carriage 
control, data, and trailing carriage control. Taken together, these three parts are 
called the composite data record. 

Leading and trailing carriage control are determined by the type of carriage 
control used in the file and explicit carriage-control information returned with 
each record. For embedded carriage control, however, leading and trailing 
carriage control is always null. 

The type of carriage control returned by the main input routine on the PSM$K_ 
OPEN request code determines, for that invocation of the input routine, how 
the symbiont applies carriage control to each record that the main input routine 
returns on the PSM$K_READ request code. 

Note that, for all four carriage control types, the first character returned on 
the first PSM$K_READ call to an input routine receives special processing. If 
that character is a linefeed or a formfeed and if the symbiont is currently at 
line 1, column 1 of the current page, then the symbiont discards that linefeed or 
formfeed. 
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The Four Types of Carriage Control 

The following table briefly describes each type of carriage control and how the 
symbiont’s main input routine processes it. For a detailed explanation of each of 
these types of carriage control, refer to the description of the FAB$B_RAT fleld of 
the FAB block in the OpenVMS Record Management Services Reference Manual. 


Type of Carriage Control 

Symbiont Processing 

Embedded 

Leading and trailing carriage control are embedded 
in the data portion of the input record. Therefore, 
the symbiont supplies no special carriage control 
processing; it assumes that leading and trailing 
carriage control are null. 

FORTRAN 

The first byte of each data record contains a 
FORTRAN carriage-control character. This character 
specifies both the leading and trailing carriage control 
for the data record. The symbiont extracts the first 
byte of each data record and interprets that byte as 
a FORTRAN carriage-control character. If the data 
record is empty, the symbiont generates a leading 
carriage control of linefeed and a trailing carriage 
control of carriage return. 

PRN 

Each data record contains a two-byte header that 
contains the carriage-control specifier. The first byte 
specifies the carriage control to apply before printing 
the data portion of the record. The second byte 
specifies the carriage control to apply after printing 
the data portion. The abbreviation PRN stands for 
print-file format. 


Unlike other types of carriage control, PRN carriage 
control information is returned through the funcarg 
argument of the main input routine; this occurs with 
the PSM$K_READ request. The funcarg argument 
specifies a longword; your routine writes the 2-byte 
PRN carriage control specifier into the first two bytes 
of this longword. 

Implied 

The symbiont provides a leading linefeed and a trailing 
carriage return. But if the data record consists of a 
single formfeed, the symbiont sets to null the leading 
and trailing carriage control for that record, and the 
leading carriage control for the record that follows it. 


12.3.3 Writing a Format Routine 

To write a format routine, follow the modiflcation procedure described in 
Section 12.3. Do not replace the symbiont’s main format routine. Instead, 
modify its action by writing input and output filter routines. These execute 
immediately before and after the main format routine, respectively. The main 
formatting routine uses an undocumented and nonpublic interface; you cannot 
replace the main formatting routine. The DCL command PRINT/PASS ALL 
bypasses the main format routine of the print symbiont. 

See Section 12.3.5 for additional information about other function codes used in 
the user-written formatting routine. 
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12.3.3.1 Internal Logic of the Symbiont’s Main Format Routine 

The main format routine contains all the logic necessary to convert composite 
data records to a data stream for output. Actions taken by the format routine 
include the following: 

• Tracking the current column and line 

• Implementing the special processing of the first character of the first record 

• Implementing the alignment data mask specified by the DCL command 
START/QUEUE/ALIGN=MASK 

• Handling margins as specified by the forms definition 

• Initiating processing of page headers when specified by the DCL command 
PRINT/HEADER 

• Expanding leading and trailing carriage control 

• Handling line overflow 

• Handling page overflow 

• Expanding tab characters to spaces for some devices 

• Handling escape sequences 

• Accumulating accounting information 

• Implementing double-spacing when specified by the DCL command PRINT 
/SPACE 

• Implementing automatic page ejection when specified by the DCL command 
PRINT/FEED 

The symbiont’s main format routine uses a special rule when processing the 
first character of the first composite data record returned by an input routine. 

(A composite data record is the input data record and a longword that contains 
carriage-control information for the input data record.) This rule is that if the 
first character is a vertical format effector (formfeed or linefeed) and if the 
symbiont has processed no printable characters on the current page (that is, 
the current position is column 1, line 1), then that vertical format effector is 
discarded. 

12.3.4 Writing an Output Routine 

To write an output routine, follow the modification procedure described in 
Section 12.3. 

The print symbiont calls your output routine. Input arguments are supplied by 
the print symbiont; output arguments and status values are returned by your 
routine to the print symbiont. For this reason, your output routine must have the 
call interface that is described in the USER-OUTPUT-ROUTINE routine. 

When the print symbiont calls your routine, it specifies in one of the input 
arguments—the func argument—the reason for the call. Each reason has a 
corresponding function code. 

There are several function codes that the print symbiont can supply when it 
calls your output routine. Your routine must contain the logic to respond to the 
following function codes: PSM$K_OPEN, PSM$K_WRITE, PSM$K_WRITE_ 
NOFORMAT, and PSM$K_CLOSE. 
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It is not required that your output routine contain the logic to respond to the 
other function codes, but you can provide this logic if you want to. 

A complete list and description of all relevant function codes for output routines 
is provided in the description of the func argument of the USER-OUTPUT- 
ROUTINE routine. 

See Section 12.3.5 for additional information about other function codes. 

12.3.4.1 Internal Logic of the Symbiont’s Main Output Routine 

When the symbiont calls the main output routine with the PSM$K_OPEN 
function code, the main output routine takes the following steps: 

1. Allocates the print device 

2. Assigns a channel to the device 

3. Obtains the device characteristics 

4. Returns the device-status longword in the funcarg argument (for more 
information, see the description of the SMBMSG$K_DEVICE_STATUS 
message item in Chapter 13 

5. Returns an error if the device is not a terminal or a printer 

When this routine receives a PSM$K_WRITE service request code, it sends the 
contents of the symbiont output buffer to the device for printing. 

When this routine receives a PSM$K_WRITE_NOFORMAT service request code, 
it sends the contents of the symbiont output buffer to the device for printing and 
suppresses device drive formatting as appropriate for the device in use. 

When this routine receives a PSM$K_CANCEL service request code, it requests 
the device driver to cancel any outstanding output operations. 

When this routine receives a PSM$K_CLOSE service request code, it deassigns 
the channel to the device and deallocates the device. 

12.3.5 Other Function Codes 

A status PSM$_PENDING might not be returned whenever the symbiont notifies 
user-written input, output, and format routines using the following message 
function codes: 


Function Code 

Description 

PSM$K_START_STREAM 

Job controller sends a message to the symbiont to start 
a queue 

PSM$K_START_TASK 

Symbiont parses a message from job controller 
directing it to start a queue 

PSM$K_PAUSE_TASK 

Job controller sends a message to the symbiont to 
suspend processing of the current task 

PSM$K_STOP_STREAM 

Job controller sends a message to the symbiont to stop 
the queue 

PSM$K_STOP_TASK 

Job controller sends a message to the symbiont to stop 
the task 

PSM$K_RESUME_TASK 

Job controller sends a message to the symbiont to 
resume processing of the current task 

PSM$K_RESET_STREAM 

Same as PSM$K_STOP_STREAM 
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12.3.6 Writing a Symbiont Initialization Routine 

Writing a symbiont initialization routine involves writing a program that calls 
the following: 

1. PSM$REPLACE once for each routine (input, output, or format) that you 
have written. PSM$REPLACE identifies your routines to the symbiont. 

2. PSM$PRINT exactly once after you have identified all your service routines 
using PSM$REPLACE. 

Table 12-1 lists all routine codes that you can specify in the PSM$REPLACE 
routine. Choosing the correct routine code for your routine is important because 
the routine code specifies when the symbiont will call your routine. The functions 
of these routines are described further in the description of the PSM$REPLACE 
routine. 

Column one in Table 12-1 lists each routine code. 

For those input routines that execute in a predefined sequence, the second column 
contains a number showing the order in which that input routine is called relative 
to the other input routines for a single file job. If the routine does not execute in 
a predefined sequence, the second column contains the character x. 

Column three specifies whether the routine is an input, format, or output routine; 
this information directs you to the section describing how to write a routine of 
that type. 

Column four specifies whether there is a symbiont-supplied routine corresponding 
to that routine code. The codes for the input-filter and output-filter routines, 
which have no corresponding routines in the symbiont, allow you to specify new 
routines for inclusion in the symbiont. 

Table 12-1 Routine Codes for Specification to PSM$REPLACE 

Routine Code Sequence Function Supplied 


PSM$K_JOB_SETUP 

1 

Input 

Yes 

PSM$K_FORM_SETUP 

2 

Input 

Yes 

PSM$K_JOB_FLAG 

3 

Input 

Yes 

PSM$K_JOB_BURST 

4 

Input 

Yes 

PSM$K_FILE_SETUP 

5 

Input 

Yes 

PSM$K_FILE_FLAG 

6 

Input 

Yes 

PSM$K_FILE_BURST 

7 

Input 

Yes 

PSM$K_FILE_SETUP_2 

8 

Input 

Yes 

PSM$K_MAIN_INPUT 

9 

Input 

Yes 

PSM$K_FILE_INFORMATION 

10 

Input 

Yes 

PSM$K_FILE_ERRORS 

11 

Input 

Yes 

PSM$K_FILE_TRAILER 

12 

Input 

Yes 

PSM$K_JOB_RESET 

13 

Input 

Yes 

PSM$K_JOB_TRAILER 

14 

Input 

Yes 

PSM$K_JOB_COMPLETION 

15 

Input 

Yes 


(continued on next page) 
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Table 12-1 (Cent.) Routine Codes for Specification to PSM$REPLACE 


Routine Code 

Sequence 

Function 

Supplied 

PSM$K_PAGE_SETUP 

X 

Input 

Yes 

PSM$K_PAGE_HEADER 

X 

Input 

Yes 

PSM$K_LIBRARY_INPUT 

X 

Input 

Yes 

PSM$K_INPUT_FILTER 

X 

Formatting 

No 

PSM$K_MAIN_FORMAT 

X 

Formatting 

Yes 

PSM$K_OUTPUT_FILTER 

X 

Formatting 

No 

PSM$K_OUTPUT 

X 

Output 

Yes 


12.3.7 Integrating a Modified Symbiont 

To integrate your user routine and the symbiont initialization routine, perform 
the following steps; note that the sequence of steps described here assumes that 
you will be debugging the modified symbiont: 

1. Compile or assemble the user routine and the symbiont initialization routine 
into an object module. 

2. Enter the following DCL command: 

$ LINK/DEBUG your-symbiont 

The file name your-symhiont is the object module built in step 1. Symbols 
necessary for this link operation are located in the shareable images 
SYS$SHARE:SMBSRVSHR.EXE and SYS$LIBRARY:IMAGELIB.EXE. 

The linker automatically searches these shareable images and extracts the 
necessary information. 

3. Place the resulting executable symbiont image in SYS$SYSTEM. 

4. Locate two unallocated terminals: one at which to issue DCL commands and 
one at which to debug the symbiont image. 

5. Log in on one of the terminals under UIC [1,4], which is the system manager’s 
account. This terminal is the one at which you enter DCL commands. Do not 
log in at the other terminal. 

6. Enter the following DCL command: 

$ SET TERMINAL/NODISCONNECT/PERMANENT _TTcu: 

The variable _TTcu: is the physical terminal name of the terminal at which 
you want to debug (the terminal you are not logged in at). The underscore 
(_) and colon (:) characters must be specified. 

7. Enter the following DCL commands: 

$ DEFINE/GROUP DBG$INPUT _TTcu: 

$ DEFINE/GROUP DBG$OUTPUT _TTcu: 

The variable _TTcu: specifies the physical terminal name of the terminal at 
which you will be debugging. Note that other users having a UIC with group 
number 1 should not use the debugger at the same time. 

8. Initialize the queue by entering the following DCL command: 

$ INITIALIZE/QUEUE/PROCESSOR= your-symbiont /0N= printer_name 
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The symbiont image specified by the file name your-symbiont must reside in 
SYS$SYSTEM. Note too that the /PROCESSOR qualifier accepts only a file 
name; the device, directory, and file type default to SYS$SYSTEM:.EXE. 

The /ON qualifier specifies the device that will be served by the symbiont 
while you debug the symbiont. 

9. Enter the following DCL command to execute the modified symbiont routine: 

$ PRINT/HEADER/QUEUE=queue-id 

Enter the following DCL command to start the queue and invoke the 
debugger: 

$ START/QUEUE queue-name 

10. After you debug your symbiont, relink the symbiont by entering the following 
DCL command: 

$ LINK/NOTRACEBACK/NODEBUG your-symbiont 

11. Deassign the logical names DBG$INPUT and DBG$OUTPUT so that they 
will not interfere with other users in UIC group 1. 

12.4 Example of Using the PSM Routines 

Example 12-1 shows how to use PSM routines to supply a page header routine in 
a VAX MACRO program. 

Example 12-1 Using PSM Routines to Supply a Page Header Routine in a VAX MACRO 
Program 

.TITLE EXAMPLE - Example user modified symbiont 
.IDENT 'V03-000' 


THIS PROGRAM SUPPLIES A USER WRITTEN PAGE HEADER 
ROUTINE TO THE STANDARD SYMBIONT. THE PAGE HEADER 
INCLUDES THE SUBMITTER'S ACCOUNT NAME AND USER NAME, 

THE FULL FILE SPECIFICATION, AND THE PAGE NUMBER. 

THE HEADER LINE IS UNDERLINED BY A ROW OF DASHES 
PRINTED ON A SECOND HEADER LINE. 

.LIBRARY /SYS$LIBRARY:LIB.MLB/ 

System definitions 

$PSMDEF ; Symbiont definitions 

$SMBDEF ; Message item definitions 

$DSCDEF ; Descriptor definitions 

Define argument offsets for user supplied services called by symbiont 


CONTEXT 

= 04 

; symbiont context 

WORK AREA 

= 08 

; user context 

FUNC 

= 12 

; function code 

FUNC DESC 

= 16 

; function dependent descriptor 

FUNC ARG 

= 20 

; function dependent argument 


(continued on next page) 
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Example 12-1 (Cont.) Using PSM Routines to Supply a Page Header Routine in a 

VAX MACRO Program 


; Macro to create dynamic descriptors 


/ 

.MACRO D DESC 




.WORD 

0 

; DSC$W LENGTH = 0 


.BYTE 

DSC$K DTYPE T 

; DSC$B DTYPE = STRING 


.BYTE 

DSC$K CLASS D 

; DSC$B CLASS = DYNAMIC 


.LONG 

0 

; DSC$A POINTER = 0 


.ENDM 



f 

; Storage for page header information 


1 

FILE: 

D DESC 

; file name descriptor 


USER: 

D DESC 

; user name descriptor 


ACCOUNT: 

D_DESC 

; account name descriptor 


PAGE: 

.LONG 0 

; page number 


LINE: 

.LONG 0 

; line number 

; FAO 

control string and work buffer. Header 

format: 


"[account,name] 

filename . Page 9999" 


FAO CTRL: 

.ASCID /!71<[!AS, !AS 

] !AS!>Page 9999/ 


FAO CTRL 2: 

.ASCID /!4UL/ 



FAO DESC: 

.LONG 80 

; work buffer descriptor 



.ADDRESS FAO BUFF 



FAO__BUFF: 

.BLKB 80 

; work buffer 

; Own 

storage for values passed by reference 



CODE: 

.LONG 0 

; service or item code 


STREAMS: 

.LONG 1 

; number of simultaneous streams 


BUFSIZ: 

.LONG 2048 

; output buffer size 


LINSIZ: 

.WORD 81 

; line size for underlines 

; Main 

routine — invoked at image startup 


START: 

.WORD 0 

; save nothing because this routine uses only RO and R1 


Supply private page header routine 


MOVZBL 

#PSM$K PAGE HEADER,CODE 

; set the 

service code 

PUSHAL 

HEADER 

; address 

of modified routine 

PUSHAL 

CODE 

; address 

of service code 

CALLS 

#2,G"PSM$REPLACE 

; replace 

the routine 

BLBC 

R0,10$ 

; exit if 

any errors 


; Transfer control to the standard symbiont 

PUSHAL BUFSIZ 
PUSHAL STREAMS 
CALLS #2,G"PSM$PRINT 
10$: RET 


address of output buffer size 
address of number of streams 
invoke standard symbiont 


(continued on next page) 
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Example 12-1 

(Cent.) Using PSM Routines to Supply a Page Header Routine 



VAX MACRO Program 



/ 

Page 

header routine 



HEADER: .WORD 

0 

save nothing 


7 

; Check function code 



1 

CMPL 

#PSM$K START TASK,@FUNC(AP) 

new task? 



BEQL 

20$ 

branch if so 



CMPL 

#PSM$K READ,@FUNC(AP) 

READ function? 



BNEQ 

15$ 




BRW 

50$ 

branch if so 


15$: 

CMPL 

#PSM$K OPEN, @FUNC(AP) 

OPEN function? 



BNEQ 

16$ 




BRW 

66$ 

branch if so 


16$: 

MOVL 

#PSM$ FUNNOTSUP,RO 

unsupported function 



RET 


return to symbiont 


! 

; Starting a new file 



20$: 

CLRL 

PAGE 

reset the page number 



MOVZBL 

#2,LINE 

and the line number 


; Get 

the account name 




MOVZBL 

#SMBMSG$K ACCOUNT NAME,CODE 

set item code 



PUSHAL 

ACCOUNT 

address of descriptor 



PUSHAL 

CODE 

address of item code 



PUSHAL 

@CONTEXT(AP) 

address of symbiont ctx 

value 


CALLS 

#3,G"PSM$READ ITEM DX 

read it 



BLBC 

R0,40$ 

branch if any errors 


; Get 

the file 

name 




MOVZBL 

#SMBMSG$K FILE SPECIFICATION,CODE ; set item code 



PUSHAL 

FILE 

address of descriptor 



PUSHAL 

CODE 

address of item code 



PUSHAL 

@CONTEXT(AP) 

address of symbiont ctx 

value 


CALLS 

#3,G"PSM$READ ITEM DX 

read it 



BLBC 

R0,40$ 

branch if any errors 


; Get 

the user 

name 




MOVZBL 

#SMBMSG$K USER NAME,CODE 

set item code 



PUSHAL 

USER 

address of descriptor 



PUSHAL 

CODE 

address of item code 



PUSHAL 

@CONTEXT(AP) 

address of symbiont ctx 

value 


CALLS 

#3,G"PSM$READ ITEM DX 

read it 



BLBC 

R0,40$ 

branch if any errors 



(continued on next page) 
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Example 12-1 (Cent.) Using PSM Routines to Supply a Page Header Routine in a 


VAX MACRO Program 

Set up the static header information that is 



$FAO_S 

CTRSTR = FAO CTRL, - 



OUTBUF = FAO DESC, - 



PI = #ACCOUNT, - 



P2 = #USER, - 

P3 = #FILE 


BLBC 

R0,40$ 


MOVL 

#PSM$ FUNNOTSUP,RO 

40$: 

RET 


; Read 

a page header 

50$: 

DECL 

LINE 


BEQL 

60$ 


BLSS 

70$ 

r 

; Insert the page number into the header 

r 

INCL 

PAGE 


MOVAB 

FAO BUFF+76,FAO DESC+4 


$FAO_S 

CTRSTR = FAO CTRL 2, - 



OUTBUF = FAO DESC, - 



PI = PAGE 


MOVAB 

FAO BUFF,FAO DESC+4 


BLBC 

R0,55$ 

; Copy 

the line 

to the symbiont's buffer 


PUSHAB 

FAO DESC 


PUSHL 

FUNC DESC(AP) 


CALLS 

#2,G'^STR$COPy_DX 

55$: 

RET 


r 

; Second line -• 

- underline header 

60$: 

PUSHL 

FUNC DESC(AP) 


PUSHAL 

LINSIZ 


CALLS 

#2,G^STR$GET1 DX 


BLBC 

R0,67$ 


MOVL 

FUNC DESC(AP),R1 


MOVL 

4(R1),R1 


MOVAB 

80(R1),R0 

65$: 

MOVB 

#"A/-/,{Rl)+ 


CMPL 

R0,R1 


BGTRU 

65$ 


MOVB 

#10,(Rl)+ 

66$: 

MOVZBL 

#SS$ NORMAL,RO 

67$: 

RET 



constant for the task 

; FAO control string desc 
; output buffer descriptor 
; account name descriptor 
; user name descriptor 
; file name descriptor 
; branch if any errors 
; unsupported function 
; return usupported status or error 


; decrement the line number 
; branch if second read 
; branch if third read 


; increment the page number 
; point to page number buffer 
; FAO control string desc 
; output buffer descriptor 
; page number 
; point to work buffer 
; return if error 


; work buffer descriptor 
; symbiont descriptor 
; copy to symbiont buffer 
; return success or any error 


; symbiont descriptor 
; number of bytes to reserve 
; reserve the space 
; exit if error 
; get address of descriptor 
; get address of buffer 
; set up transfer limit 
; fill with dashes 
; reached limit? 

; branch if not 
; extra line feed 
; set success 
; return 

(continued on next page) 
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Example 12-1 (Cont.) Using PSM Routines to Suppiy a Page Header Routine in a 

VAX MACRO Program 


; Done with this page header 
70$: 

MOVL #PSM$_EOF,RO 

MOVZBL #2,LINE 
RET 

.END START 


12.5 PSM Routines 

The following pages describe the individual PSM routines. 


; return end of input 
; reset line counter 
; return 
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PSM$PRINT—Invoke OpenVMS-Supplied Print Symbiont 

The PSM$PRINT routine invokes the OpenVMS-supplied print symbiont. 

PSM$PRINT must be called exactly once after all user service routines have been 
specified using PSM$REPLACE. 


Format 

PSM$PRINT [streams] [,bufsiz] [,worksiz] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

streams 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Maximum number of streams that the print symbiont is to support. The streams 
argument is the address of a longword containing this number, which must be 
in the range 1 to 16. If you do not specify streams, a default value of 1 is used. 
Thus, by default, a user-modified print symbiont supports one stream, which is to 
say that it is a single-threaded symbiont. 

A stream (or thread) is a logical link between a print execution queue and a 
printing device. When a symbiont process can accept simultaneous links to more 
than one queue, that is, when it can service multiple queues simultaneously, the 
symbiont is said to be multithreaded. 

bufsiz 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Maximum buffer size in bytes that the print symbiont is to use for output 
operations. The bufsiz argument is the address of a longword containing the 
specified number of bytes. 

The print symbiont actually uses a buffer size that is the smaller of (1) the value 
specified by bufsiz or ( 2 ) the system parameter MAXBUF. If you do not specify 
bufsiz, then the print symbiont uses the value of MAXBUF. 

The print symbiont uses this size limit only for output operations. Output 
operations involve the placing of processed or formatted pages into a buffer that 
will be passed to the output routine. 
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The print symbiont uses the value specified by bufsiz only as an upper limit; 
most buffers that it writes will be smaller than this value. 

worksiz 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Size in bytes of a work area to be allocated for the use of user routines. The 
worksiz argument is the address of a longword containing this size in bytes. If 
you do not specify worksiz, no work area is allocated. 

A separate area of the specified size is allocated for each active symbiont stream. 


Description 

The PSM$PRINT routine must be called exactly once after all user routines 
have been specified to the print symbiont. Each user routine is specified to the 
symbiont in a call to the PSM$REPLACE routine. 

The PSM$PRINT routine allows you to specify whether the print symbiont is to 
be single-threaded or multithreaded, and if multithreaded, how many streams or 
threads it can have. In addition, this routine allows you to control the maximum 
size of the output buffer. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

This routine also returns any condition values returned by the $SETPRV, 
$GETSYI, $PURGWS, and $DCLAST system services, as well as any condition 
values returned by the SMB$INITIALIZE routine documented in Chapter 13. 
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PSM$READ_ITEM_DX—Obtain Value of Message Items 

The PSM$READ_ITEM_DX routine obtains the value of message items that are 
sent by the job controller and stored by the symbiont. 

Format 

PSM$READJTEM_DX requestjd Jtern ,buffer 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

request_id 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Request identifier supplied by the symbiont to the user routine currently calling 
PSM$READ_ITEM_DX. The symbiont always supplies a request identifier when 
it calls a user routine with a service request. The requestjd argument is the 
address of a longword containing this request identifier value. 

Your user routine must copy the request identifier value that the symbiont 
supplies (in the requestjd argument) when it calls your user routine. Then, 
when your user routine calls PSM$READ_ITEM_DX, it must supply (in the 
requestjd argument) the address of the request identifier value that it copied. 

item 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Item code that identifies the message item that PSM$READ JTEM_DX is to 
return. The item argument is the address of a longword that specifies the item’s 
code. 

For a complete list and description of each item code, refer to the documentation 
of the item argument in the SMB$READ_MESSAGE JTEM routine in 
Chapter 13. 

buffer 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 
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Buffer into which PSM$READ_ITEM_DX returns the specified informational 
item. The buffer argument is the address of a descriptor pointing to this buffer. 

The PSM$READ_ITEM_DX routine returns the specified informational item 
by copying that item to the buffer using one of the STR$COPY_xx routines 
documented in the OpenVMS RTL String Manipulation (STR$) Manual. 


Description 

The PSM$READ_ITEM_DX routine obtains the value of message items 
that are sent by the job controller and stored by the symbiont. You use 
PSM$READ_ITEM_DX to obtain information about the task currently being 
processed, for example, the name of the file being printed (SMBMSG$K_FILE_ 
SPECIFICATION) or the name of the user who submitted the job (SMBMSG$K_ 
USER_NAME). 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

PSM$_INVITMCOD Invalid item code specified in the item argument. 

This routine also returns any condition values returned by any of the 
STR$COPY_xx routines documented in the OpenVMS RTL String Manipulation 
(STR$) Manual. 
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PSM$REPLACE— Declare User Service Routine 


Format 


Returns 


The PSM$REPLACE routine substitutes a user service routine for a symbiont 
routine or adds a user service routine to the set of symbiont routines. 

You must call PSM$REPLACE once for each routine that you replace or add. 


PSM$REPLACE code ,routine 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 


Arguments 

code 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Routine code that identifies the symbiont routine to be replaced by a user service 
routine. The code argument is the address of a longword containing the routine 
code. 

Some routine codes identify routines that are supplied with the symbiont; when 
you specify such a routine code, you replace the symbiont-supplied routine with 
your service routine. 

Two routine codes identify routines that are not supplied with the symbiont; 
when you specify such a routine code, your service routine is added to the set of 
symbiont routines. 

Table 12—1 lists each routine code in the order in which it is called within the 
symbiont execution stream; this table also specifies whether a routine code 
identifies an input, formatting, or output routine and whether the routine is 
supplied with the symbiont. 

Each programming language provides an appropriate mechanism for defining 
these routine codes. The following pages list each routine code in alphabetical 
order; the description of each code includes the following information about its 
corresponding routine: 

• Whether the routine is supplied by the symbiont 

• Whether the routine is an input, formatting, or output routine 

• Under what conditions the routine is called 

• What task the routine performs 
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Routine Codes 

PSM$K_FILE_BURST 

This code identifies a symbiont-supplied input routine; it is called whenever a file 
burst page is requested. This routine obtains information about the job, formats 
the file burst page, and returns the contents of the page to the input buffer. A file 
burst page follows a file flag page and precedes the contents of the file. 

PSM$K_FILE_ERRORS 

This code identifies a symbiont-supplied input routine; it is called when errors 
have occurred during the job. This routine places the error message text in the 
input buffer. 

PSM$K_FILE_FLAG 

This code identifies a symbiont-supplied input routine; it is called whenever a file 
flag page is requested. This routine obtains information about the job, formats 
the file flag page, and returns the contents of the page to the input buffer. A flag 
page follows the job burst page (if any) and precedes the file burst page (if any). 

It contains such information as the file specification of the file and the name of 
the user issuing the print request. 

PSM$K_FILEJNFORMATION 

This code identifies a symbiont-supplied input routine; it is called when the file 
information item has been specified by the job controller. This routine expands 
the file information item to text and returns it to the input buffer. 

PSM$K_FILE_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine queues any specified file-setup modules for insertion in the input stream 
when the PSM$K_FILE_SETUP routine closes. 

PSM$K_FILE_SETUP_2 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine returns a formfeed to ensure that printing of the file begins at the top of 
the page. This routine is called just before the main input routine. 

PSM$K_FILE_TRAILER 

This code identifies a symbiont-supplied input routine; it is called whenever a file 
trailer page is requested. This routine obtains information about the job, formats 
the file trailer page, and returns the contents of the page to the input buffer. A 
trailer page follows the last page of the file contents. 

PSM$K_MAIN_FORMAT 

This code identifies the symbiont-supplied formatting routine; it is always called. 
This routine performs numerous formatting functions. You cannot replace this 
routine. 

PSM$K_FORM_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine queues any specified form-setup modules for insertion in the input stream 
when the PSM$K_FORM_SETUP routine closes. 

PSM$KJNPUT_FILTER 

This code identifies a format routine that is not supplied by the symbiont. If 
the routine is supplied by the user, it is always called immediately prior to the 
symbiont-supplied formatting routine (routine code PSM$K_MAIN_FORMAT). An 
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input-filter service routine is useful for modifying input data records and their 
carriage control before they are formatted by the symbiont. 

PSM$K_JOB_BURST 

This code identifies a symbiont-supplied input routine; it is called whenever a job 
burst page is requested. This routine obtains information about the job, formats 
the job burst page, and returns the contents of the page to the input buffer. A job 
burst page follows the job flag page and precedes the file flag page (if any) of the 
first file in the job. It is similar to a file burst page except that it appears only 
once per job and only at the beginning of the job. 

PSM$K_JOB_COMPLETION 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine returns a formfeed, which causes any output buffered by the device to be 
printed. 

PSM$K_JOB_FLAG 

This code identifies a symbiont-supplied input routine; it is called whenever a job 
flag page is requested. This routine obtains information about the job, formats 
the job flag page, and returns the contents of the page to the input buffer. A job 
flag page is similar to a file flag page except that it appears only once per job, 
preceding the job burst page (if any). 

PSM$K_JOB_RESET 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine queues any specified job-reset modules for insertion in the input stream 
when the PSM$K_JOB_RESET routine closes. 

PSM$K_JOB_SETUP 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine checks to see if this is the first job to be printed on the device, and if so, 
it issues a formfeed and then performs a job reset. See the description of the 
PSM$K_JOB_RESET routine for information about job reset. 

PSM$K_JOB_TRAILER 

This code identifies a symbiont-supplied input routine; it is called whenever a job 
trailer page is requested. This routine obtains information about the job, formats 
the job trailer page, and returns the contents of the page to the input buffer. A 
job trailer page is similar to a file trailer page except that it appears only once 
per job, as the last page in the job. 

PSM$K_MAINJNPUT 

This code identifies a symbiont-supplied input routine; it is always called. This 
routine opens the file to be printed, returns input records to the input buffer, and 
closes the file. 

PSM$K_LIBRARYJNPUT 

This code identifies a symbiont-supplied input routine; it is called when an input 
routine closes and when modules have been requested for insertion in the input 
stream. This routine returns the contents of the specified modules, one record per 
call. You cannot replace this routine. 

PSM$K_OUTPUT_FILTER 

This code identifies a formatting routine that is not supplied by the symbiont. If 
the routine is supplied by the user, it is always called. This routine executes prior 
to the symbiont output routine (routine code PSM$K_OUTPUT). An output-filter 
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service routine is useful for modifying output data buffers before they are passed 
to the output routine. 

At the point where the output-filter routine executes within the symbiont 
execution stream, the input data is no longer in record format; instead, the data 
exists as a stream of characters. The carriage control, for example, is embedded 
in the data stream. Thus, the output buffer might contain what was once a 
complete record, part of a record, or several records. 

PSM$K_PAGE_HEADER 

This code identifies a symbiont-supplied input routine; it is called once at the 
beginning of each page if page headers are requested. This routine returns to the 
input buffer one or more lines containing information about the file being printed 
and the current page number. This routine is called only while the main input 
routine is open. 

PSM$K_PAGE_SETUP 

This code identifies a symbiont-supplied routine; it is called at the beginning of 
each page if page-setup modules were specified. This routine queues any specified 
page-setup modules for insertion in the input stream when the PSM$K_PAGE_ 
SETUP routine closes. This routine is called only while the main input routine is 
open. 

PSM$K_OUTPUT 

This code identifies the symbiont-supplied output routine; it is always called. 

This routine writes the contents of the output buffer to the printing device, but it 
also performs many other functions. 

routine 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by reference 

User service routine that is to replace a symbiont routine or to be included. The 
routine argument is the address of the user routine entry point. 


Description 

The PSM$REPLACE routine must be called each time a user service routine 
replaces a symbiont routine or is added to a set of symbiont routines. 

The code argument specifies the symbiont routine to be replaced. The routine 
codes that can be specified in the code argument are of two types: those that 
identify existing print symbiont routines and those that do not. All the routine 
codes are similar, however, in the sense that each supplies a location within the 
print symbiont execution stream where your routine can execute. 

By selecting a routine code that identifies an existing symbiont routine, you 
effectively disable that symbiont routine. The service routine that you specify 
might or might not perform the function that the disabled symbiont routine 
performs. If it does not, the net effect of the replacement is to eliminate that 
function from the list of functions performed by the print symbiont. Exactly what 
your service routine does is up to you. 
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By selecting a routine code that does not identify an existing symbiont routine 
(those that identify the input-filter and output-filter routines), your service 
routine has a chance to execute at the location signified by the routine code. 
Because the service routine you specify to execute at this location does not 
replace another symbiont routine, your service routine is an addition to the set of 
symbiont routines. 

As mentioned, each routine code identifies a location in the symbiont execution 
stream, whether or not it identifies a symbiont routine. Table 12-1 lists each 
routine code in the order in which the location it identifies is reached within the 
symbiont execution stream. 

Condition Value Returned 

SS$_NORMAL Normal successful completion. 
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PSM$REPORT—Report Completion Status 

The PSM$REPORT routine reports to the print symhiont the completion status of 
an asynchronous operation initiated by a user routine. 

Such a user routine must return the completion status PSM$_PENDING. 
PSM$REPORT must be called exactly once for each time a user routine returns 
the status PSM$_PENDING. 


Format 

PSM$REPORT requestjd [,status] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
The condition value that this routine can return is listed under Condition Value 
Returned. 


Arguments 

request_id 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Request identifier supplied by the symbiont to the user routine at the time the 
symbiont called the user routine with the service request. The user routine must 
return the completion status PSM$_PENDING on the call for this service request. 
The requestjd argument is the address of a longword containing the request 
identifier value. 

The symbiont calls the user routine with a request code that specifies the function 
that the symbiont expects the user routine to perform. In the call, the symbiont 
also supplies a request identifier, which serves to identify the request. If the 
user routine initiates an asynchronous operation, a mechanism is required for 
notifying the symbiont that the asynchronous operation has completed and for 
providing the completion status of the operation. 

The PSM$REPORT routine conveys the above two pieces of information. In 
addition, PSM$REPORT returns to the symbiont (in the requestjd argument) 
the same request identifier value as that supplied by the symbiont to the user 
routine that initiated the operation. In this way, the symbiont synchronizes the 
completion status of an asynchronous operation with that invocation of the user 
routine that initiated the operation. 

Any user routine that initiates an asynchronous operation must, therefore, 
copy the request identifier value that the symbiont supplies (in the requestjd 
argument) when it calls the user routine. The user routine will later need to 
supply this value to PSM$REPORT. 
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In addition, when the user routine returns, which it does before the asynchronous 
operation has completed, the user routine must return the status PSM$_ 
PENDING. 

status 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by reference 

Completion status of the asynchronous operation that has completed. The status 
argument is the address of a longword containing this completion status. The 
status argument is optional; if it is not specified, the symbiont assumes the 
completion status SS$_NORMAL. 

The user routine that initiates the asynchronous operation must test for the 
completion of the operation and must supply the operation’s completion status as 
the status argument to the PSM$REPORT routine. The DESCRIPTION section 
describes this procedure in greater detail. 

If the completion status specified by status has the low bit clear, the symbiont 
aborts the task. 


Description 

An asynchronous operation is an operation that, once initiated, executes “off 
to the side” and need not be completed before other operations can begin to 
execute. Asynchronous operations are common in symbiont applications because 
a symbiont, if it is multithreaded, must handle concurrent I/O operations. 

One example of a user routine that performs an asynchronous operation is 
an output routine that calls the $QIO system service to write a record to the 
printing device. When the user output routine completes execution, the I/O 
request queued by $QIO might not have completed. In order to synchronize this 
I/O request, that is, to associate the I/O request with the service request that 
initiated it, you should use the following mechanism: 

1. In making the call to $QIO, specify the astadr and iosb arguments. The 
astadr argument specifies an AST routine to execute when the queued output 
request has completed, and the iosb argument specifies an I/O status block 
to receive the completion status of the I/O operation. Item 3 describes some 
functions that your AST routine will need to do. 

2. Have the user output routine return the status PSM$_PENDING. 

3. Write the AST routine to perform the following functions: 

a. Copy the completion status word from the I/O status block to a longword 
location that you will specify as the status argument in the call to 
PSM$REPORT. 

b. Call PSM$REPORT. Specify as the requested argument the request 
identifier that was supplied by the print symbiont in the original call to 
the user output routine. 
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Condition Vaiue Returned 

SS$_NORMAL 


Normal successful completion. 
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USER-FORMAT-ROUTINE—Invoke User-Written Format Routine 

The user-written USER-FORMAT-ROUTINE performs format operations. The 
symbiont’s control logic routine calls your format routine at one of two possible 
points within the symbiont’s execution stream. You select this point by specifying 
one of two routine codes when you call the PSM$REPLACE routine. 

A user format routine can be an input filter routine (routine code PSM$K_ 
INPUT_FILTER) or an output filter routine (routine code PSM$K_OUTPUT_ 
FILTER). The main format routine (routine code PSM$K_MAIN_FORMAT) 
cannot be replaced. 

A user format routine must use the call interface described here. 


Format 


Returns 


USER-FORMAT-ROUTINE requestjd ,work_area ,func ,func_desc_1 ,func_arg_1 

,func_desc_2 ,func_arg_2 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

request_id 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Request identifier supplied by the symbiont when it calls your format routine. 
The requestjd argument is the address of a longword containing this request 
identifier value. 

work_area 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Work area supplied by the symbiont for the use of your format routine. The 
symbiont supplies the address of this area when it calls your routine. The work_ 
area argument is a longword containing the address of the work area. The work 
area is a section of memory that your format routine can use for buffering and 
other internal operations. 

The size of the work area allocated is specified by the work_size argument in the 
PSM$PRINT routine. If you do not specify work_size in the call to PSM$PRINT, 
no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each thread. 
This work area is shared by all user routines. The work area is initialized to zero 
when the symbiont is first started. 

func 

OpenVMS usage function_code 
type longword (unsigned) 

access read only 

mechanism by reference 

Function code specifying the service that the symbiont expects your format 
routine to perform. The func argument is the address of a longword into which 
the symbiont writes this function code. 

The function code specifies the reason the symbiont is calling your format routine 
or, in other words, the service that the symbiont expects your routine to perform 
at this time. 

The PSM$K_FORMAT function code is the only one to which your format routine 
must respond. When the symbiont calls your format routine with this function 
code, your routine must move a record from the input buffer to the output buffer. 

The symbiont can call your format routine with other function codes. Your routine 
should return the status PSM$_FUNNOTSUP (function not supported) when it 
is called with any of the following function codes or with any undocumented 
function code. When the status PSM$_FUNNOTSUP is returned, the symbiont 
performs its normal action as if no format routine were supplied. To suppress the 
symbiont’s normal action, you should return SS$_NORMAL. 

PSM$K_START_STREAM PSM$K_STOP_STREAM 

PSM$K_START_TASK PSM$K_PAUSE_TASK 

PSM$K_RESUME_TASK PSM$K_STOP_TASK 

PSM$K_RESET_STREAM 

These function codes correspond to message items, which are discussed in more 
detail in Section 12.3.5, sent by the job controller to the symbiont. 

Other function codes correspond to internal symbiont mechanisms that are not 
part of the public interface to the print symbiont. 

Your format routine should return the status PSM$_FUNNOTSUP or SS$_ 
NORMAL when it is called with a message function code or with a private 
function code. 

func_desc_1 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Descriptor supplying an input record to be processed by the format routine. 

The func_desc_l argument is the address of a string descriptor. By using this 
argument, the symbiont supplies the input record that your format routine 
is to process. Because this descriptor can be of any valid string type, your 
format routine should use the Run-Time Library string routines to analyze this 
descriptor and to manipulate the input record. 


PSM-35 



Print Symbiont Modification (PSM) Routines 
USER-FORMAT-ROUTINE 


func_arg_1 

OpenVMS usage vector_byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Carriage control for the input record supplied by func_desc_l. The func_arg_l 
argument is the address of a 4-byte vector that specifies the carriage control for 
the input record. The following diagram depicts the format of this 4-b3de vector: 
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Bytes 0 and 1 describe the leading carriage control to apply to the input data 
record; bytes 2 and 3 describe the trailing carriage control. 

Byte 0 is a number specifying the number of times the carriage control specifier 
in byte 1 is to be repeated preceding the input data record. Byte 2 is a number 
specifying the number of times the carriage control specifier in byte 3 is to be 
repeated following the input data record. 

For values of the carriage control specifier from 1 to 255, the specifier is the 
ASCII character to be used as carriage control. Value 0 represents the ASCII 
“newline” sequence. Newline consists of a carriage return followed by a linefeed. 

The func_arg_l argument is not used if your format routine is an output filter 
routine (routine code PSM$K_OUTPUT_FILTER). See the DESCRIPTION section 
for more information. 

func_desc_2 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by reference 

Descriptor of a buffer to which your format routine writes the formatted output 
record. The func_desc_2 argument is the address of a string descriptor. 

Your format routine must return the formatted data record by using the func_ 
desc_2 argument. 

Your format routine should use the Run-Time Library string routines to write 
into the buffer specified by this descriptor. 

func_arg_2 

OpenVMS usage vector_byte_unsigned 
type byte (unsigned) 

access write only 

mechanism by reference 

Carriage control for the output record returned in func_desc_2. The func__arg_2 
argument is the address of a 4-byte vector that specifies the carriage control for 
the output record. See the description of func_arg_l for the contents and format 
of this 4-byte vector. 
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If you do not process the carriage-control information supplied in func_arg_l , 
then you should copy that value into func_arg_2. Otherwise, the carriage-control 
information will be lost. 

The func_arg_2 argument is not used if your format routine is an output filter 
routine (routine code PSM$K_OUTPUT_FILTER). See the DESCRIPTION section 
for more information. 

Description 

When used, the func_arg_l argument describes carriage-control information for 
the input data record, and the func_arg_2 argument describes carriage-control 
information for the output data record. 

The input data record is passed to the format routine (input filter or output filter) 
for processing, and the output data record is returned by the format routine 
(input filter or output filter). 

One of the tasks performed by the main format routine (routine code PSM$K_ 
MAIN_FORMAT) is that of embedding the carriage-control information (specified 
by func_arg_l) into the data record (specified by func_desc_l). Thus, the output 
data (specified by func__desc_2) contains embedded carriage control and is thus 
no longer in record format; it is, therefore, properly referred to as an output data 
stream rather than an output data record. 

Similarly, the output filter routine (routine code PSM$K_OUTPUT_FILTER), 
which executes after the main format routine, uses neither the func_arg_l nor 
func_arg_2 argument; the data it receives (via func_desc_l) and the data it 
returns (via func_desc_2) are data streams, not data records. 

However, the input filter routine (routine code PSM$K_INPUT_FILTER), which 
executes before the main format routine, uses both func_arg_l and func_arg_2. 
This is so because the main format routine has not yet executed, and so the 
carriage control information has not yet been embedded in the data record. 

Condition Values Returned 

SS$_NORMAL Successful completion. The user format routine 

has completed the function that the symbiont 
requested. 

PSM$_FUNNOTSUP Function not supported. The user format routine 

does not support or does not recognize the 
function code supplied by the symbiont. To 
ensure future compatibility, your format routine 
should return this status for any unrecognized 
status codes. 

This routine also returns any error condition values that you have coded your 
format routine to return. Refer to Section 12.3.1 for more information about error 
condition values. 
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USER-INPUT-ROUTINE—Invoke User-Written Input Routine 

The user-written USER-INPUT-ROUTINE performs input operations. The 
symbiont calls your routine at a specified point in its execution stream; you 
specify this point using the PSM$REPLACE routine. 


Format 

USER-INPUT-ROUTINE requestjd ,work_area ,func ,funcdesc ,funcarg 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

request_id 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Request identifier value supplied by the symbiont when it calls your input 
routine. The requestjd argument is the address of a longword containing this 
request identifier value. 

If your input routine initiates an asynchronous operation (for example, a call to 
the $QIO system service), your input routine must copy the request identifier 
value specified by requestjd because this value must later be passed to the 
PSM$REPORT routine. See the description of the PSM$REPORT routine for 
more information. 

work_area 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Work area supplied by the symbiont for the use of your input routine. The 
symbiont supplies the address of this area when it calls your routine. The work__ 
area argument is a longword into which the symbiont writes the address of the 
work area. The work area is a section of memory that your input routine can use 
for buffering and for other internal operations. 

The size of the work area allocated is specified by the work_size argument in the 
PSM$PRINT routine. If you do not specify work_size in the call to PSM$PRINT, 
no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each thread. 
This work area is shared by all user routines. The work area is initialized to zero 
when the symbiont is first started. 

func 

OpenVMS usage function_code 
type longword (unsigned) 

access read only 

mechanism by reference 

Function code supplied by the symbiont when it calls your input routine. The 
func argument is the address of a longword containing this code. 

The function code specifies the reason the symbiont is calling your input routine 
or, in other words, the function that the symbiont expects your routine to perform 
at this time. 

Most function codes require or allow additional information to be passed in the 
call by means of the funcdesc and funcarg arguments. The description of each 
input function code, therefore, includes a description of how these two arguments 
are used with that function code. 

Following is a list of all the function codes that the symbiont can specify when 
it calls your input routine (function codes applicable only to format and output 
routines are explained in the descriptions of the USER-FORMAT-ROUTINE and 
USER-OUTPUT-ROUTINE, respectively); all function codes are defined by the 
$PSMDEF macro. 

Function Codes for Input Routines 

PSM$K_CLOSE 

When the symbiont calls your routine with this function code, your routine must 
terminate processing by releasing any resources it might have allocated. 

The symbiont calls your routine with PSM$K_CLOSE when (1) your routine 
returns from a PSM$K_READ function call with the status PSM$_EOF (end of 
input) or with any error condition, or (2) the symbiont receives a task-abortion 
request from the job controller. 

In any event, the symbiont always calls your input routine with PSM$K_CLOSE 
if your routine returns successfully from a PSM$K_OPEN function call. This 
guaranteed behavior ensures that any resources your routine might have 
allocated on the OPEN will be released on the CLOSE. 

PSM$K_GET_KEY 

Typically, the use of both the PSM$K_GET_KEY and PSMK$K_POSITION_TO_ 
KEY function codes is appropriate only for a main input routine (routine code 
PSM$K_MAIN_INPUT). 

When the symbiont calls your routine with this function code, your routine can 
do one of two things: (1) return PSM$_FUNNOTSUP (function not supported) or 
(2) return an input marker string to the symbiont. 

If your routine returns PSM$_FUNNOTSUP to this function code, then your 
routine must also return PSM$_FUNNOTSUP if the symbiont subsequently calls 
your routine with the PSM$K_POSITION_TO_KEY function code. By returning 
PSM$_FUNNOTSUP, your routine is choosing not to respond to the symbiont 
request. 
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If your routine chooses to respond to the PSM$K_GET_KEY function code, your 
routine must return an input marker string to the symbiont; this input marker 
string identifies the input record that your input routine most recently returned 
to the symbiont. Subsequently, when the symbiont calls your input routine with 
the PSM$K_POSITION_TO_KEY function code, the symbiont passes your input 
routine one of the input marker strings that your input routine has returned on 
a previous PSM$K_GET_KEY function call. Using this marker string, your input 
routine must position itself so that, on the next PSM$K_READ call from the 
symbiont, your input routine will return (or reread) the input record identified by 
the marker string. 

Coding your input routine to respond to PSM$K_GET_KEY and PSM$K_ 
POSITION_TO_KEY allows the modified symbiont to perform the file-positioning 
functions specified by the DCL commands START/QUEUE/FORWARD, START 
/QUEUE/ALIGN, START/QUEUE/TOP_OF_FILE, START/QUEUE/SEARCH, and 
START/QUEUE/BACKWARD. These file positioning functions also depend on the 
job controller’s checkpointing capability for print jobs. 

Note that your input routine might be called with a marker string that was 
originally returned in a different process context from the current one. This can 
occur because marker strings are sometimes stored in the queue-data file across 
system shutdowns or different invocations of your symbiont. 

The funcdesc argument specifies the address of a string descriptor. Your routine 
must return the marker string by way of this argument. Digital recommends that 
you use one of the Run-Time Library string routines to copy the marker string to 
the descriptor. 

The symbiont periodically calls your input routine with the PSM$K_GET_KEY 
function code when the symbiont wants to save a marker to a particular input 
record. 

PSM$K_OPEN 

When the symbiont calls your routine with this function code, your routine should 
prepare for input operations by performing such tasks as allocating necessary 
resources, initializing storage areas, opening an input file, and so on. Typically, 
the next time the symbiont calls your input routine, the symbiont will specify the 
PSM$K_READ function code. Note, however, that under some circumstances the 
symbiont might follow an OPEN call immediately with a CLOSE call. 

The funcdesc argument points to the name of the file to be opened. Your routine 
can use this file specification or the file identifcation to open the file. 

The funcarg argument specifies the address of a longword. Your input routine 
must return, in this longword, the carriage control type that is to be applied to 
the input records that your input routine will provide. 

The symbiont formatting routine requires this information to determine where to 
apply leading and trailing carriage control characters to the input records that 
your input routine will provide. 
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The $PSMDEF macro defines the following four carriage control types: 


Carriage Type 

Description 

PSM$K_CC_IMPLIED 

Implied carriage control. For this type, the 
symbiont inserts a leading linefeed (LF) and 
trailing carriage return (CR) in each input record. 
This is the default carriage control type; it is used 
if your routine does not supply a carriage control 
type in the funcarg argument in response to the 
PSM$K_OPEN function call. 

PSM$K_CC_FORTKAN 

FORTRAN carriage control. For this type, the 
symbiont extracts the first byte of each input record 
and interprets the byte as a FORTRAN carriage 
control character, which it then applies to the input 
record. 

PSM$K_CC_PRINT 

PRN carriage control. For this type, the symbiont 
generates carriage control from a 2 -byte record 
header that your input routine supplies, with each 
READ call, in the funcarg argument. The funcarg 
argument specifies the address of a longword to 
receive this two-byte header record, which appears 
only in PRN print files. 

PSM$K_CC_INTERNAL 

Embedded carriage control. For this type, the 
symbiont supplies no carriage control to input 
records. Carriage control is assumed to be 
embedded in the input records. 


PSM$K_POSITION_TO_KEY 

When the symbiont calls your routine with this function code, your routine must 
locate the point in the input stream designated by the marker string that your 
routine returned to the symbiont on the PSM$K_GET_KEY function call. 

The next time the symbiont calls your routine, the symbiont specifies the PSM$K_ 
READ function call, expecting to receive the next sequential input record. After 
rereading this record, subsequent READ calls proceed from this new position of 
the file. This is not a one-time rereading of a single record but a repositioning 
of the file. The symbiont calls your routine with this function code when the job 
controller receives a request to resume printing at a particular page. 

Refer to the description of the PSM$K_GET_KEY for more information. 

PSM$K_READ 

When the symbiont calls your routine with this function code, your routine must 
return an input record. The symbiont repeatedly calls your input routine with 
the PSM$K_READ function code until (1) your routine indicates end of input by 
returning the status PSM$_EOF, (2) your routine or another routine returns an 
error status, or (3) the symbiont receives an asynchronous task-abortion request 
from the job controller. 

The funcdesc argument specifies the address of a string descriptor. Your routine 
must return the input record by using this argument. Digital recommends that 
you use one of the Run-Time Library string routines to copy the input record to 
the descriptor. 


PSM-41 


Print Symbiont Modification (PSM) Routines 
USER-INPUT-ROUTINE 


The funcarg argument specifies the address of a longword. This argument is 
used only if the carriage control type returned by your input routine on the 
PSM$K_OPEN function call was PSM$K_CC_PRINT In this case, your input 
routine must supply, in the funcarg argument, the 2-byte record header found at 
the beginning of each input record. 

PSM$K_REWIND 

When the symbiont calls your routine with this function code, your routine must 
do one of two things: (1) return PSM$_FUNNOTSUP (function not supported) or 
(2) locate the point in the input stream designated as the beginning of the file. 

If your routine returns PSM$_FUNNOTSUP to this function code, then 
the symbiont subsequently calls your input routine with a PSM$K_CLOSE 
function call followed by a PSM$K_OPEN function call. By returning PSM$_ 
FUNNOTSUP, your routine is choosing not to support the repositioning of the 
input service to the beginning of the file. The symbiont, therefore, performs the 
desired function by closing and then reopening the input routine. 

You cannot use the funcdesc and the funcarg arguments with this function 
code. 

This function call allows the modified symbiont to perform the file-positioning 
functions specified by the DCL commands START/QUEUE/TOP_OF_FILE, 
START/QUEUE/FORWARD, START/QUEUE/BACKWARD, START/QUEUE 
/SEARCH, and START/QUEUE/ALIGN. This is a required repositioning of the 
file. 

Other Input Function Codes 

The symbiont can call your input routine with other function codes. Your routine 
must return the status PSM$_FUNNOTSUP (function not supported) when it 
is called with any of the following function codes or with any undocumented 
function code. When the status PSM$_FUNNOTSUP is returned, the symbiont 
performs its normal action as if no input routine were supplied. To suppress the 
symbiont’s normal action, you should return SS$_NORMAL. 

PSM$K_START_STREAM PSM$K_STOP_STREAM 

PSM$K_START_TASK PSM$K_PAUSE_TASK 

PSM$K_RESUME_TASK PSM$K_STOP_TASK 

PSM$K_RESET_STREAM 

These function codes correspond to message items, which are discussed in detail 
in Section 12.3.5, sent by the job controller to the symbiont. 

Other function codes correspond to internal symbiont mechanisms that are not 
part of the public interface to the print symbiont. 

Your input routine should return the status PSM$_FUNNOTSUP or SS$_ 
NORMAL when it is called with a message function code or with a private 
function code. 

funcdesc 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Function descriptor supplying information related to the function specified by the 
func argument. The funcdesc argument is the address of this descriptor. 
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The contents of the function descriptor vary for each function. Refer to the 
description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 

funcarg 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Function argument supplying information related to the function specified by the 
func argument. The funcarg argument is the address of a longword containing 
this function argument. This argument can be an input or an output argument, 
depending on the function request, but is usually used as an output argument. 

Condition Values Returned 

SS$_NORMAL Successful completion. The user input routine 

has completed the function that the symbiont 
requested. 

PSM$_FLUSH Flush output stream. The user input routine 

can return this status only when called with the 
PSM$K_READ function code. When this status 
is returned to the symbiont, the symbiont stops 
calling the input routine with the PSM$K_READ 
function code until all outstanding format and 
output operations have completed. 

PSM$_FUNNOTSUP Function not supported. The user input routine 

does not support or does not recognize the 
function code supplied by the symbiont. To 
ensure future compatibility, your input routine 
should return this status for any unrecognized 
status codes. 

PSM$_PENDING Requested function accepted but not completed. 

Your input routine can return this status only 
with the PSM$K_READ function call. Further, if 
your routine returns PSM$_PENDING, your 
routine must eventually signal completion 
via the PSM$REPORT routine. Refer to the 
description of the PSM$REPORT routine for 
more information about asynchronous operations 
and the PSM$_PENDING condition value. 

This routine also returns any error condition values that you have coded your 
format routine to return. Refer to Section 12.3.1 for more information about error 
condition values. 
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USER-OUTPUT-ROUTINE—Invoke User-Written Output Routine 

The user-written USER-OUTPUT-ROUTINE performs output operations. You 
supply a user output routine by calling the PSM$REPLACE routine with the 
routine code PSM$K_OUTPUT 


Format 

USER-OUTPUT-ROUTINE requestjd ,work_area ,func ,funcdesc ,funcarg 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

request_ld 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Request identifier value supplied by the symbiont when it calls your output 
routine. The requestjd argument is the address of a longword containing this 
value. 

If your output routine initiates an asynchronous operation (for example, a call to 
the Queue I/O Request (SYS$QIO) system service), you must save the request^ 
id argument because you will need to store the request identifier value for later 
use with the PSM$REPORT routine. See the description of the PSM$REPORT 
routine for more information. 

work_area 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Work area supplied by the symbiont for the use of your format routine. The 
symbiont supplies the address of this area when it calls your routine. The work_ 
area argument is a longword containing the address of the work area. The work 
area is a section of memory that your format routine can use for buffering and 
other internal operations. 

The size of the work area allocated is specified by the work_size argument in the 
PSM$PRINT routine. If you do not specify work_size in the call to PSM$PRINT, 
no work area is allocated. 
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In a multithreaded symbiont, a separate work area is allocated for each thread. 
This work area is shared by all user routines. The work area is initialized to zero 
when the symbiont is first started. 

func 

OpenVMS usage function_code 
type longword (unsigned) 

access read only 

mechanism by reference 

Function code supplied by the symbiont when it calls your output routine. The 
func argument is the address of a longword containing this code. 

The function code specifies the reason the symbiont is calling your output routine 
or, in other words, the function that the symbiont expects your routine to perform 
at this time. 

Most function codes require or allow additional information to be passed in the 
call via the funcdesc and funcarg arguments. The description of each output 
function code, therefore, includes a description of how these two arguments are 
used for that function code. 

The following list describes all the function codes that the symbiont might supply 
when it calls your output routine (function codes applicable only to input and 
formatting routines are explained in the descriptions of the user input routine 
and user formatting routine, respectively). Each programming language provides 
an appropriate mechanism for defining these function codes. 

Function Codes for Output Routines 

PSM$K_OPEN 

When the symbiont calls your output routine with this function code, your routine 
should prepare to move data to the device by performing such tasks as allocating 
the device, assigning a channel to the device, and so on. The next time the 
symbiont calls your output routine, the symbiont specifies one of the WRITE 
function codes (PSM$K_WRITE or PSM$K_WRITE_NOFORMAT). 

The symbiont calls your output routine with the PSM$K_OPEN function code 
when the symbiont receives the SMBMSG$K_START_STREAM message from the 
job controller. 

If your output routine returns an error condition value (low bit clear) to the 
PSM$K_OPEN function call, the job controller stops processing on the stream 
and reports the error to whomever entered the DCL command START/QUEUE. 

The funcdesc argument is the address of a descriptor that identifies the name of 
the device the output routine is to write to. This device name is established by 
the DCL command INITIALIZE/QUEUE/ON=device-name. 

The funcarg argument is the address of a longword into which the user output 
routine returns the device status longword. For the contents of the device status 
longword, refer to the description of the SMBMSG$K_DEVICE_STATUS item in 
the SMB$READ_MESSAGE_ITEM routine, which is documented in Chapter 13. 

Your output routine sets bits in the device status longword to indicate to the job 
controller whether the device falls into one of the following categories: 

• Can print lowercase letters 

• Is a terminal 
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• Is connected to the CPU by means of a modem (remote) 

If your output routine does not set any of these bits in the device status longword, 
the job controller assumes, by default, that the device is a line printer that prints 
only uppercase letters. 

PSM$K_WRITE 

When the symbiont calls your routine with this function code, your routine must 
write data to the device. The symbiont supplies the data to be written in the 
funcdesc argument. Digital recommends that you use one of the Run-Time 
Library string routines to access the data in the buffer described by the funcdesc 
argument. 

PSM$K_WRITE_NOFORMAT 

When the symbiont calls your routine with this function code, your routine must 
write data to the device and must indicate to the device driver that the data is 
not to be formatted. 

The symbiont calls your routine with this function code when (1) the print 
request specifies the PASSALL option or (2) data is introduced by the ANSI DCS 
(device control string) escape sequence. 

The symbiont supplies the data to be written in the funcdesc argument. Digital 
recommends that you use one of the Run-Time Library string routines to move 
the data from the descriptor to the device. 

The output routine of the symbiont informs the device driver not to format the 
data in the following way: 

• When the device is a line printer, the symbiont’s output routine specifies the 
IO$_WRITEPBLK function code when it calls the $QIO system service. 

• When the device is a terminal, the symbiont’s output routine specifies the 
IO$M_NOFORMAT function modifier when it calls the $QIO system serivce. 

PSM$K_CANCEL 

When the symbiont calls your routine with this function code, your routine must 
abort any outstanding asynchronous I/O requests. 

The output routine supplied by the symbiont aborts outstanding I/O requests by 
calling the $CANCEL system service with the IO$_CANCEL function code. 

If your output routine returned the condition value PSM$_PENDING to one or 
more previous write requests that are still outstanding (that is, PSM$REPORT 
has not yet been called to report completion), then your output routine must 
call PSM$REPORT one time for each outstanding write request that is canceled 
with this call. That is, canceling an asynchronous write request does not relieve 
the user output routine of the requirement to call PSM$REPORT once for each 
asynchronous write request. 

You cannot use the funcdesc and funcarg arguments with this function code. 

PSM$K_CLOSE 

When the symbiont calls your routine with this function code, your output routine 
must terminate processing and release any resources it allocated (for example, 
channels assigned to the device). 

You cannot use the funcdesc and funcarg arguments with this function code. 
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Other Output Function Codes 

The symbiont can call your output routine with other function codes. Your routine 
should return the status PSM$_FUNNOTSUP (function not supported) when it 
is called with any of the following function codes or with any undocumented 
function code. When the status PSM$_FUNNOTSUP is returned, the symbiont 
performs its normal action as if no output routine were supplied. To suppress the 
symbiont’s normal action, you should return SS$_NORMAL. 

PSM$K_START_STREAM PSM$K_STOP_STREAM 

PSM$K_START_TASK PSM$K_PAUSE_TASK 

PSM$K_RESUME_TASK PSM$K_STOP_TASK 

PSM$K_RESET_STREAM 

These function codes correspond to message items, which are discussed in more 
detail in Section 13.1.6, sent by the job controller to the symbiont. 

Other function codes correspond to internal symbiont mechanisms that are not 
part of the public interface to the print symbiont. 

Your output routine should return the status PSM$_FUNNOTSUP or SS$_ 
NORMAL when it is called with a message function code or with a private 
function code. 

funcdesc 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Function descriptor supplying information related to the function specified by the 
func argument. The funcdesc argument is the address of this descriptor. 

The contents of the function descriptor vary for each function. Refer to the 
description of each function code to determine the contents of the function 
descriptor. In some cases, the function descriptor is not used at all. 

funcarg 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by reference 

Function argument supplying information related to the function specified by the 
func argument. The funcarg argument is the address of a longword containing 
this function argument. 

The contents of the function argument vary for each function. Refer to the 
description of each function code to determine the contents of the function 
argument. In some cases, the function argument is not used. 

Condition Values Returned 

SS$_NORMAL Successful completion. The user output routine 

has completed the function that the symbiont 
requested. 
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PSM$_FUNNOTSUP 


PSM$_PENDING 


This routine also returns 
output routine to return, 
condition values. 


Function not supported. The user output routine 
does not support or does not recognize the 
function code supplied by the symbiont. To 
ensure future compatibility, your output routine 
should return this status for any unrecognized 
status codes. 

Requested function accepted but not completed. 
Your output routine can return this status only 
with PSM$K_WRITE and PSM$K_WRITE_ 
NOFORMAT function calls. Further, if your 
routine returns PSM$_PENDING, your routine 
must eventually signal completion by way 
of the PSM$REPORT routine. Refer to the 
description of the PSM$REPORT routine for 
more information about asynchronous write 
operations and the PSM$_PENDING condition 
value. 

any error condition values that you have coded your 

Refer to Section 12.3.1 for more information about error 
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Symbiont/Job Controller Interface (SMB) 

Routines 


The Symbiont/Job Controller Interface (SMB) routines provide the interface 
between the job controller and symbiont processes. A user-written symbiont must 
use these routines to communicate with the job controller. 

13.1 Introduction to SMB Routines 

Always use the SMB interface routines or the SYS$SNDJBC or SYS$GETQUI 
system services to communicate with the job controller. You need not and should 
not attempt to communicate directly with the job controller. 

To write your own symbiont, you need to understand how symbionts work and, in 
particular, how the standard print symbiont behaves. 

13.1.1 Types of Symbiont 

There are two types of symbiont: 

• Device symbiont, either an input symbiont or an output symbiont. An input 
symbiont is one that transfers data from a slow device to a fast device, for 
example, from a card reader to a disk. A card-reader symbiont is an input 
symbiont. An output symbiont is one that transfers data from a fast device 
to a slow device, for example, from a disk to a printer or terminal. A print 
symbiont is an output symbiont. 

• Server symbiont, a symbiont that processes or transfers data but is not 
associated with a particular device; one example is a symbiont that transfers 
files across a network. 

The operating system does not supply any server symbionts. 

13.1.2 Symbionts Supplied with the Operating System 

The operating system supplies two symbionts: 

• SYS$SYSTEM:PRTSMB.EXE (PRTSMB for short), an output symbiont for 
use with printers and printing terminals. 

PRTSMB performs such functions as inserting flag, burst, and trailer pages 
into the output stream; reading and formatting input files; and writing 
formatted pages to the printing device. 

You can modify PRTSMB using the Print Symbiont Modification (PSM) 
routines. 

• SYS$SYSTEM:INPSMB.EXE (INPSMB for short) an input symbiont for use 
with card readers. 
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This symbiont handles the transferring of data from a card reader to a disk 
file. You cannot modify INPSMB, nor can you write an input symbiont using 
the SMB routines. 

13.1.3 Symbiont Behavior in the OpenVMS Environment 

In the OpenVMS environment, a symbiont is a process under the control of the 
job controller that transfers or processes data. 

Figure 13-1 depicts the components that take part in the handling of user 
requests that involve symbionts. This figure shows two symbionts: (1) the print 
symbiont supplied by the operating system, PRTSMB, and (2) a user-written 
symbiont, GRAPHICS.EXE, which services a graphics plotter. The numbers in 
the figure correspond to the numbers in the list that follows. 

This list does not reflect the activities that must be performed by the hypothetical, 
user-written symbiont, GRAPHICS.EXE. This symbiont is represented in the 
figure to illustrate the correspondence between a user-written symbiont and the 
print symbiont supplied by the operating system. 

Although SMB routines can be used for a different kind of symbiont, many 
of their arguments and associated symbols have names related to the print 
symbiont. The print symbiont is presented here as an example of a typical 
symbiont and illustrates points that are generally true for symbionts. 

O You request a printing job with the DCL command PRINT. DCL calls the 
Send to Job Controller (SYS$SNDJBC) system service, passing the name of 
the file to be printed to the job controller, along with any other information 
specified by qualifiers for the PRINT command. 

0 The job controller places the print request in the appropriate queue and 
assigns the request a job number. 

0 The job controller breaks the print job into a number of tasks (for example, 
printing three copies of the same file is three separate tasks). The job 
controller makes a separate request to the symbiont for each task. 

Each request that the job controller makes consists of a message. Each 
message consists of a code that indicates what the symbiont is to do and a 
number of items of information that the symbiont needs to carry out the task 
(the name of the file, the name of the user, and so on.) 

O PRTSMB interprets the information it receives from the job controller. 

@ PRTSMB locates and opens the file it is to print by using the file-identification 
number the job controller specified in the start-task message. 

© PRTSMB sends the data from the file to the printer’s driver. 

O The device driver sends the data to the printer. 
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Figure 13-1 Symbionts in the OpenVMS Environment 
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13.1.4 Writing a Symbiont 

Writing your own symbiont permits you to use the queueing mechanisms and 
control functions of the job controller. You might want to do this if you need a 
symbiont for a device that cannot be served by PRTSMB (or a modified form 
of PRTSMB) or if you need a server symbiont. The interface between the job 
controller and the symbiont permits the symbiont you write to use the many 
features of the job controller. 

For example, when you use the DCL command PRINT to print a file, the job 
controller sends a message to the print symbiont telling it to print the file. 
However, when a user-written symbiont receives the same message (caused by 
entering a PRINT command), it might interpret it to mean something quite 
different. A robot symbiont, for example, might interpret the message as a 
command for movement and the file specification (specified with the PRINT 
command) might be a file describing the directions in which the robot is to move. 

_ Note _ 

Modifying PRTSMB is easier than writing your own symbiont; choose 
this option if possible. The Print Symbiont Modification (PSM) routines 
describe how to modify PRTSMB to suit your needs. 
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13.1.5 Guidelines for Writing a Symbiont 

Although you can write a symbiont to use the queuing mechanisms and other 
features of the job controller in whatever way you want, you must follow these 
guidelines to ensure that your symbiont works correctly: 

• The symbiont must not use any of the process-permanent channels, which are 
assigned to the following logical names: 

- SYS$INPUT 

- SYS$OUTPUT 

- SYS$ERROR 

- SYS$COMMAND 

• The symbiont must allocate and deallocate memory using the RTL routines 
LIB$GET_VM and LIB$FREE_VM. 

• To be compatible with future releases of the operating system, you should 
write the symbiont to ignore unknown message-item codes and unknown 
message-request codes. (See the SMB$READ_ITEM_MESSAGE routine.) 

• The symbiont must communicate with the job controller by using the Job- 
Controller/Symbiont Interface (SMB) routines, the SYS$SNDJBC system 
service, and the SYS$GETQUI system service. 

• The symbiont should not perform lengthy operations within the context of an 
AST routine. The symbiont can only receive messages from the job controller 
when it is not executing within the context of an AST routine. 

• The symbiont code should be linked against SMBSRVSHR.EXE in order to 
define the SMB routine address and the following status codes: 

- SMB$_INVSTMNBR 

- SMB$_INVSTRLEV 

- SMB$_NOMOREITEMS 

• To assign a symbiont to a queue after it is compiled and linked, the executable 
image of the symbiont must reside in SYS$SYSTEM, and you must enter 
either of the following commands: 

INITIALIZE/QUEUE/PROCESSOR=symbiont_filename 

START/QUEUE/PROCESSOR=symbiontJilename 

You should specify only the file name in the command. The disk and directory 
default to SYS$SYSTEM, and all fields except the file name are ignored. 

• To help debug symbionts, you should define the logical names DBG$INPUT 
and DBG$OUTPUT in the LNM$GROUP_000001 logical name table to point 
to your debugging terminal. 
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13.1.6 The Symbiont/Job-Controller Interface Routines 

The five SMB routines form a public interface to the job controller. The job 
controller delivers requests to symbionts by means of this interface, and the 
symbionts communicate their responses to those requests through this interface. 
A user-written symbiont uses the following routines to exchange messages with 
the job controller: 

SMB$INITIALIZE Initializes the SMB facility’s internal database, 

establishes the interface to the job controller, and 
defines whether 

• Messages from the job controller are to be 
delivered to the symbiont synchronously or 
asynchronously with respect to execution of 
the symbiont. 

• The symbiont is to be single-threaded or 
multithreaded; these concepts are described 
in the sections that follow. 


SMB$CHECK_FOR_MESSAGE 

SMB$READ_MESSAGE 

SMB$READ_MESSAGE_ITEM 

SMB$SEND_TO_JOBCTL 


Checks to see if a message from the job 
controller to the symbiont has arrived (used 
with synchronous symbionts) 

Reads the job controller’s message into a buffer 

Returns one item of information from the job 
controller’s message (which can have several 
informational items) 

Sends a message from the symbiont to the job 
controller 


The following sections discuss how to use the SMB routines when writing your 
symbiont. 


13.1.7 Choosing the Symbiont Environment 

The first SMB routine that a symbiont must call is the SMB$INITIALIZE 
routine. In addition to allocating and initializing the SMB facility’s internal 
database, it offers you two options for your symbiont environment: synchronous 
or asynchonous delivery of messages from the job controller and single streaming 
or multistreaming the symbiont. 

13.1.7.1 Synchronous Versus Asynchronous Delivery of Requests 

When you initialize your job controller/symbiont interface, the symbiont 
has the option of accepting requests from the job controller sychronously or 
asynchronously. 

Synchronous Environment 

The address of an AST routine is an optional argument to the SMB$INITIALIZE 
routine; if it is not specified, the symbiont receives messages from the job 
controller synchronously. A symbiont that receives messages synchronously 
must call SMB$CHECK_FOR_MESSAGE periodically during the processing of 
tasks in order to ensure the timely delivery of STOP_TASK, PAUSE_TASK, and 
RESET_STREAM requests. 

SMB$CHECK_FOR_MESSAGE checks to see if a message from the job controller 
is waiting. If a message is waiting, SMB$CHECK_FOR_MESSAGE returns 
a success code. The caller of SMB$CHECK_FOR_MESSAGE can then call 
SMB$READ_MESSAGE to read the message and take the appropriate action. 


SMB-5 


Symbiont/Job Controller Interface (SMB) Routines 
13.1 Introduction to SMB Routines 


If no message is waiting, SMB$CHECK_FOR_MESSAGE returns a zero in RO. 
The caller of SMB$CHECK_FOR_MESSAGE can continue to process the task at 
hand. 

Figure 13-2 is a flowchart for a synchronous, single-threaded symbiont. The 
flowchart does not show all the details of the logic the symbiont needs and does 
not show how the symbiont handles Pause-task, Resume-task, or Reset-stream 
requests. 


Figure 13~2 Flowchart for a Single-Threaded, Synchronous Symbiont 



Asynchronous Environment 

To receive messages asynchronously, a symbiont specifles a message-handling 
AST routine as the second argument to the SMB$INITIALIZE routine. In this 
scheme, whenever the job controller sends messages to the symbiont, the AST 
routine is called. 
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The AST routine is called with no arguments and returns no value. You have 
the option of having the AST routine read the message within the context of its 
execution or of having the AST routine wake a suspended process to read the 
message outside the context of the execution of the AST routine. 

Be aware that an AST can be delivered only while the symbiont is not executing 
within the context of an AST routine. Thus, in order to ensure delivery of 
messages from the job controller, the symbiont should not perform lengthy 
operations at AST level. 

This is particularly important to the execution of STOP_TASK, PAUSE_TASK, 
and RESET_STREAM requests. If a STOP_TASK request cannot be delivered 
during the processing of a task, for example, it is useless. 

One technique that ensures delivery of STOP and PAUSE requests in an 
asynchronous environment is to have the AST routine set a flag if it reads a 
PAUSE_TASK, STOP.TASK, or a RESET_STREAM request and to have the 
symbiont’s main routine periodically check the flag. 

Figure 13-3 and Figure 13-4 show a logic chart for a single-threaded, 
asynchronous symbiont. The figures do not show many details that your symbiont 
might include, such as a call to the $QIO system service. 

Note that the broken lines in Figure 13—3 that connect the calls to SYS$HIBER 
with the AST routine’s calls to SYS$WAKE show that the next action to take 
place is the call to SYS$WAKE. They do not accurately represent the flow of 
control within the symbiont but represent the action of the job controller in 
causing the AST routine to execute. 

13.1.7.2 Single-Streaming Versus Multistreaming 

A single-stream (or thread) is a logical link between a queue and a symbiont 
process. When a symbiont process is linked to more than one queue and serves 
those queues simultaneously, it is called a multithreaded symbiont. 

The argument to the SMB$READ_MESSAGE routine provides a way for 
a multithreaded symbiont to keep track of the stream referred to by a 
request. Writing your own multithreaded symbiont, however, can be a complex 
undertaking. 
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Figure 13-3 Flowchart for a Single-Threaded, Asynchronous Symbiont (MAIN Routine) 



SMB-8 























Symbiont/Job Controller Interface (SMB) Routines 
13.1 Introduction to SMB Routines 

Figure 13-4 Flowchart for a Single-Threaded, Asynchronous Symbiont (AST Routine) 
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13.1.8 Reading Job Controller Requests 

Table 13-1 lists the seven general functions that the job controller can request of 
the symbiont. 

Table 13-1 Job Controller Functions 

SMBMSG$K_START_STREAM 
SMBMSG$K_START_TASK 
SMBMSG$K_RESUME_TASK 
SMBMSG$K_RESET_STREAM 


SMBMSG$K_STOP_STREAM 

SMBMSG$K_PAUSE_TASK 

SMBMSG$K_STOP_TASK 


The job controller passes these requests to the symbiont in a structure that 
contains (1) a code that identifies the requested function and (2) optional items 
of information that the symbiont might need to perform the requested function. 

By calling SMB$READ_MESSAGE, the symbiont reads the function code and 
writes the associated items of information, if any, into a buffer. The symbiont 
then parses the message items stored in the buffer by calling the SMB$READ_ 
MESSAGE_ITEM routine. SMB$READ_MESSAGE_ITEM reads one message 
item each time it is called. 

Each message item consists of a code that identifies the type of information the 
item contains, and the information itself. For example, the SMBMSG$K_JOB_ 
NAME code tells the symbiont that the item contains a string, which is the name 
of a job. 

The number of message items in a request message varies with each type of 
request. Therefore, to ensure that all message items are read, SMB$READ_ 
MESSAGE_ITEM must be called repeatedly for each request. SMB$READ_ 
MESSAGE_ITEM returns status SMB$_NOMOREITEMS after it has read the 
last message item in a given request. 

Typically, a symbiont checks the code of a message item against a case table and 
stores the message string in an appropriate variable until all the message items 
are read and the processing of the request can begin. 

See the description of the SMB$READ_MESSAGE_ITEM routine for a table that 
shows the message items that make up each type of request. 

13.1.9 Processing Job Controller Requests 

After a request is read, it must be processed. The way a request is processed 
depends on the type of request. The following section lists, for each request that 
the job controller sends to the print symbiont, the actions that the standard 
symbiont (PRTSMB) takes when the message is received. These actions are 
oriented toward print symbionts in particular but can serve as a guideline for 
other kinds of symbionts as well. 

The symbiont you write can respond to requests in a similar way or in a different 
way appropriate to the function of your symbiont. Digital suggests that your 
routines follow the guidelines described in this document. (Note that the behavior 
of the standard symbiont is subject to change without notice in future versions of 
the operating system.) 


SMB-10 




Symbiont/Job Controller Interface (SMB) Routines 
13.1 Introduction to SMB Routines 


SMBMSG$K_START_STREAM 

• Reset all stream-specific information that might have been altered by previous 
START_STREAM requests on this stream (for multithreaded symbionts). 

• Read and store the message items associated with the request. 

• Allocate the device specified by the SMBMSG$K_DEVICE_NAME item. 

• Assign a channel to the device. 

• Obtain the device characteristics. 

• If the device is neither a terminal nor a printer, then abort processing and 
return an error to the job controller by means of the SMB$SEND_TO_ 
JOBCTL routine. Note that, even though an error has occurred, the stream 
is still considered started. The job controller detects the error and sends a 
STOP_STREAM request to the symbiont. 

• Set temporary device characteristics suited to the way the symbiont will use 
the device. 

• For remote devices (devices connected to the system by means of a modem) 
establish an AST to report loss of the carrier signal. 

• Report to the job controller that the request has been completed and that the 
stream is started, by specifying SMBMSG$K_START_STREAM in the call to 
SMB$SEND_TO_JOBCTL. 

SMBMSG$K_START_TASK 

• Reset all task-specific information that might have been altered by previous 
START_TASK requests on this stream number. 

• Read and store the message items associated with the request. 

• Open the main input file. 

• Report to the job controller that the task has been started by specifying 
SMBMSG$K_START_TASK in the call to the SMB$SEND_TO_JOBCTL 
routine. 

• Begin processing the task. 

• When the task is complete, notify the job controller by specifying 
SMBMSG$K_TASK_COMPLETE in the call to the SMB$SEND_TO_JOBCTL 
routine. 

SMBMSG$K_PAUSE_TASK 

• Read and store the message items associated with the request. 

• Set a flag that will cause the main processing routine to pause at the 
beginning of the next output page. 

• When the main routine pauses, notify the job controller by specifying 
SMBMSG$K_PAUSE_TASK in the call to the SMB$SEND_TO_JOBCTL 
routine. 
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SMBMSG$K_RESUME_TASK 

• Read and store the message items associated with the request. 

• Perform any positioning functions specified by the message items. 

• Clear the fiag that causes the main input routine to pause, and resume 
processing the task. 

• Notify the job controller that the task has been resumed by specifying 
SMBMSG$K_RESUME_TASK in the call to the SMB$SEND_TO_JOBCTL 
routine. 

SMBMSG$K_STOP_TASK 

• Read and store the message items associated with the request. 

• If processing of the current task has paused, then resume it. 

• Cancel any outstanding I/O operations. 

• Close the input file. 

• If the job controller specified, in the START_TASK message, that a trailer 
page should be printed when the task is stopped or if it specified that the 
device should be reset when the task is stopped, then perform those functions. 

• Notify the job controller that the task has been stopped abnormally by 
specifying SMBMSG$K_STOP_TASK and by specifying an error vector in 
the call to SMB$SEND_TO_JOBCTL. PRTSMB specifies the value passed by 
the job controller in the SMBMSG$K_STOP_CONDITION item as the error 
condition in the error vector. 

SMBMSG$K_STOP_STREAM 

• Read and store the message items associated with the request. 

• Release any stream-specific resources: (1) deassign the channel to the device, 
and (2) deallocate the device. 

• Notify the job controller that the stream has been stopped by specifying 
SMBMSG$K_STOP_STREAM in the call to SMB$SEND_TO_JOBCTL. 

• If this is a single-threaded symbiont or if this is a multithreaded symbiont 
but all other streams are currently stopped, then call the SYS$EXIT system 
service with the condition code SS$_NORMAL. 

SMBMSG$K_RESET_STREAM 

• Read and store the message items associated with the request. 

• Abort any task in progress—you do not need to notify the job controller that 
the task has been aborted, but you can do so if you want. 

• If the job controller specified, in the START_TASK message, that a trailer 
page should be printed when the task is stopped or if it specified that 
the device should be reset when the task is stopped, then suppress those 
functions. 

The job controller sends the symbiont a RESET_STREAM request to regain 
control of a queue or a device that has failed to respond to a STOP_TASK 
request. The RESET_STREAM request should avoid any further I/O activity 
if possible. The printer might be disabled, for example, and requests for 
output on that device will never be completed. 
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• Continue as if this were a STOP_STREAM request. 

_ Note _ 

A STOP_STREAM request and a RESET_STREAM request each stop the 
queue; but a RESET_STREAM request is an emergency stop and is used, 
for example, when the device has failed. A RESET_STREAM request 
should prevent any further I/O activity because the printer might not be 
able to complete it. 


13.1.10 Responding to Job Controller Requests 

The symbiont uses the SMB$SEND_TO_JOBCTL routine to send messages to the 
job controller. 

Most messages that the symbiont sends to the job controller are responses to 
requests made by the job controller. Such messages inform the job controller 
that the request has been completed successfully or unsuccessfully. The function 
code that the symbiont returns to the controller in the call to SMB$SEND_TO_ 
JOBCTL indicates what request has been completed. 

For example, if the job controller sends a START_TASK request using the 
SMBMSG$K_START_TASK code, the symbiont responds by calling SMB$SEND_ 
TO_JOBCTL using SMBMSG$K_START_TASK as the request argument to 
indicate that task processing has begun. Until the symbiont responds, the DCL 
command SHOW QUEUE indicates that the queue is starting. 

The responses to some requests use additional arguments to send more 
information than just the request code. See the SMB$SEND_TO_JOBCTL 
routine for a table showing the additional arguments allowed in response to each 
request. 

In addition to sending messages in response to requests, the symbiont can send 
other messages to the job controller. In these messages the symbiont sends either 
the SMBMSG$K_TASK_COMPLETE code, indicating that it has completed a 
task, or SMBMSG$K_TASK_STATUS, indicating that the message contains 
information on the status of a task. 

Note that, when a START_TASK request is delivered, the symbiont responds with 
a SMB$SEND_TO_JOBCTL message with the SMBMSG$K_START_TASK code. 
This response means the task has been started. It does not mean the task has 
been completed. When the symbiont completes the task, it calls SMB$SEND_TO_ 
JOBCTL with the SMBMSG$K_TASK_COMPLETE code. 

13.2 SMB Routines 

The following pages describe the individual SMB routines. 
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SMB$CHECK_FOR_MESSAGE—Check for Message from Job 

Controller 

The SMB$CHECK_FOR_MESSAGE routine determines whether a message sent 
from the job controller to the symbiont is waiting to be read. 


Format 

SMB$CHECK_FOR_MESSAGE 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

None. 


Description 

When your symbiont calls the SMB$INITIALIZE routine to initialize the interface 
between the symbiont and the job controller, you can choose to have requests from 
the job controller delivered by means of an AST. If you choose not to use ASTs, 
your symbiont must call SMB$CHECK_FOR_MESSAGE during the processing of 
tasks in order to see if a message from the job controller is waiting to be read. If 
a message is waiting, SMB$CHECK_FOR_MESSAGE returns a success code; if 
not, it returns a zero. 

If a message is waiting, the symbiont should call SMB$READ_MESSAGE to read 
it to determine if immediate action should be taken (as in the case of STOP_ 
TASK, RESET_STREAM or PAUSE_TASK). 

If a message is not waiting, SMB$CHECK_MESSAGE returns a zero. If this 
condition is detected, the symbiont should continue processing the request at 
hand. 

Condition Values Returned 

SS$_NORMAL One or more messages waiting. 

0 No messages waiting. 
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SMB$INITIALIZE—Initialize User-Written Symbiont 

The SMB$INITIALIZE routine initializes the user-written symbiont and the 
interface between the symbiont and the job controller. It allocates and initializes 
the internal databases of the interface and sets up the mechanism that is to wake 
up the symbiont when a message is received. 


Format 


SMB$INITIALIZE structurejevel [,ast_routine] [,streams] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

structure_level 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Version of the job-controller/symbiont interface. The structurejevel argument 
is the address of a longword containing the version of the job-controller/symbiont 
interface used when the symbiont was compiled. Always place the value of the 
symbol SMBMSG$K_STRUCTURE_LEVEL in the longword addressed by this 
argument. Each programming language provides an appropriate mechanism for 
defining symbols. 

ast_routine 

OpenVMS usage ast_procedure 
type procedure value 

access read only 

mechanism by reference 

Message-handling routine called at AST level. The ast_routine argument is the 
address of the entry point of the message-handling routine to be called at AST 
level when the symbiont receives a message from the job controller. The AST 
routine is called with no parameters and returns no value. If an AST routine is 
specified, the routine is called once each time the symbiont receives a message 
from the job controller. 

The AST routine typically reads the message and determines if immediate action 
must be taken. Be aware that an AST can be delivered only while the symbiont 
is operating at non-AST level. Thus, to ensure delivery of messages from the job 
controller, the symbiont should not perform lengthy operations at AST level. 
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The ast_routine argument is optional. If you do not specify it, the symbiont 
must call the SMB$CHECK_FOR_MESSAGE routine to check for waiting 
messages. 

streams 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Maximum number of streams the symbiont is to support. The streams argument 
is the address of a longword containing the number of streams that the symbiont 
is to support. The number must be in the range 1 to 32. 

If you do not specify this argument, a default value of 1 is used. Thus, by default, 
a symbiont supports one stream. Such a symbiont is called a single-threaded 
symbiont. 

A stream (or thread) is a logical link between a queue and a symbiont. 

When a symbiont is linked to more than one queue, and serves those queues 
simultaneously, it is called a multithreaded symbiont. 


Description 

Your symbiont must call SMB$INITIALIZE before calling any other SMB$ 
routines. It calls SMB$INITIALIZE in order to do the following: 

• Allocate and initialize the SMB$ facility’s internal database. 

• Establish the interface between the job controller and the symbiont. 

• Determine the threading scheme of the symbiont. 

• Set up the mechanism to wake your symbiont when a message is received. 

After the symbiont calls SMB$INITIALIZE, it can communicate with the job 
controller using the other SMB$ services. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

SMB$_INVSTRLEV Invalid structure level. 

SMB$_INVSTMNBR On VAX systems only, indicates the value for 

streams argument not a valid number. 

This routine also returns any codes returned by $ASSIGN and LIB$GET_VM. 
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SMB$READ_MESSAGE—Obtain Message Sent by Job Controller 

The SMB$READ_MESSAGE routine copies a message that the job controller has 
sent into the caller’s specified buffer. 


Format 

SMB$READ_MESSAGE stream ,buffer ,request 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

stream 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Stream number specifying the stream to which the message refers. The stream 
argument is the address of a longword into which the job controller writes the 
number of the stream referred to by the message. In single-threaded symbionts, 
the stream number is always 0. 

buffer 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Address of the descriptor that points to the buffer into which the job controller 
writes the message. SMB$READ_MESSAGE uses the RTL STR$ string-handling 
routines to copy the message into the buffer you supply. The buffer should be 
specified by a dynamic string descriptor. 

request 

OpenVMS usage identifier 
type longword (unsigned) 

access write only 

mechanism by reference 

Code that identifies the request. The request argument is the address of a 
longword into which SMB$READ_MESSAGE writes the code that identifies the 
request. 
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There are seven request codes. Each code is interpreted as a message by the 
symbiont. The codes and their descriptions follow: 


SMBMSG$K_START_STREAM 


SMBMSG$K_STOP_STREAM 


SMBMSG$K_RESET_STREAM 


SMBMSG$K_START_TASK 


SMBMSG$K_STOP_TASK 


SMBMSG$K_PAUSE_TASK 


SMBMSG$K_RESUME_TASK 


Initiates processing on an inactive symbiont 
stream. The job controller sends this 
message when a START/QUEUE or an 
INITIALIZE/QUEUE/START command is 
issued on a stopped queue. 

Stops processing on a started queue. The 
job controller sends this message when a 
STOP/QUEUE/NEXT command is issued, 
after the symbiont completes any currently 
active task. 

Aborts all processing on a started stream 
and requeues the current job. The job 
controller sends this message when a STOP 
/QUEUE/RESET command is issued. 

Requests that the symbiont begin processing 
a task. The job controller sends this message 
when a file is pending on an idle, started 
queue. 

Requests that the symbiont abort the 
processing of a task. The job controller sends 
this message when a STOP/QUEUE/ABORT 
or STOP/QUEUE/REQUEUE command 
is issued. The item SMBMSG$K_STOP_ 
CONDITION identifies whether this is an 
abort or a requeue request. 

Requests that the symbiont pause in the 
processing of a task but retain the resources 
necessary to continue. The job controller 
sends this message when a STOP/QUEUE 
command is issued without the /ABORT, 
/ENTRY, /REQUEUE, or /NEXT qualifier for 
a queue that is currently printing a job. 

Requests that the symbiont continue 
processing a task that has been stopped 
with a PAUSE_TASK request. This message 
is sent when a START/QUEUE command is 
issued for a queue served by a symbiont that 
has paused in processing the current task. 


Description 

Your symbiont calls SMB$READ_MESSAGE to read a message that the job 
controller has sent to the symbiont. 

Each message from the job controller consists of a code identifying the function 
the symbiont is to perform and a number of message items. There are seven 
codes. Message items are pieces of information that the symbiont needs to carry 
out the requested function. 

For example, when you enter the DCL command PRINT, the job controller sends 
a message containing a START_TASK code and a message item containing the 
specification of the file to be printed. 
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SMB$READ_MESSAGE writes the code into a longword (specified by the 
request argument) and writes the accompanying message items, if any, into a 
buffer (specified by the buffer argument). 

See the description of the SMB$READ_MESSAGE_ITEM routine for information 
about processing the individual message items. 

Condition Values Returned 

SS$_NORMAL Routine completed successfully. 

LIB$_INVARG Routine completed unsuccessfully because of an 

invalid argument. 

This routine also returns any of the condition codes returned by the Run-Time 
Library string-handling (STR$) routines. 
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SMB$READ_MESSAGE_ITEM—Parse Next Item from Message 

Buffer 

The SMB$READ_MESSAGE_ITEM routine reads a buffer that was filled in by 
the SMB$READ_MESSAGE routine, parses one message item from the buffer, 
writes the item’s code into a longword, and writes the item into a buffer. 


Format 

SMB$READ_MESSAGEJTEM message ,context ,item_code .buffer [.size] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 


message 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Message items that SMB$READ_MESSAGE_ITEM is to read. The message 
argument is the address of a descriptor of a buffer. The buffer is the one that 
contains the message items that SMB$READ_MESSAGE_ITEM is to read. The 
buffer specified here must be the same as that specified with the call to the 
SMB$READ_MESSAGE routine, which fills the buffer with the contents of the 
message. 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Value initialized to 0 specifying the first message item in the buffer to be read. 
The context argument is the address of a longword that the SMB$READ_ 
MESSAGE_ITEM routine uses to determine the next message item to be 
returned. When this value is 0, it indicates that SMB$READ_MESSAGE_ 

ITEM is to return the first message item. 

The SMB$READ_MESSAGE_ITEM routine updates this value each time it reads 
a message item. SMB$READ_MESSAGE_ITEM sets the value to 0 when it has 
returned all the message items in the buffer. 
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item_code 

OpenVMS usage smb_item 
type longword (unsigned) 

access write only 

mechanism by reference 

Item code specified in the message item that identifies its type. The item_code 
argument is the address of a longword into which SMB$READ_MESSAGE_ITEM 
writes the code that identifies what item it is returning. 

The codes that identify message items are defined at the end of the 
DESCRIPTION section for this routine. 

buffer 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Message item. The buffer argument is the address of a descriptor of a buffer. 
The buffer is the one in which the SMB$READ_MESSAGE_ITEM routine is to 
place the message item data. SMB$READ_MESSAGE_ITEM uses the RTL STR$ 
string-handling routines to copy the message item data into the buffer. 

size 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Size of the message item. The size argument is the address of a word in which 
the SMB$READ_MESSAGE_ITEM is to place the size, in bytes, of the item’s 
data. 


Description 

The job controller can request seven functions from the symbiont. They are 
identified by the following codes: 

SMBMSG$K_START_STREAM SMBMSG$K_STOP_STREAM 

SMBMSG$K_START_TASK SMBMSG$K_PAUSE_TASK 

SMBMSG$K_RESUME_TASK SMBMSG$K_STOP_TASK 

SMBMSG$K_RESET_STREAM 

The job controller passes the symbiont a request containing a code and, optionally, 
a number of message items containing information the symbiont might need to 
perform the function. The code specifies what function the request is for, and 
the message items contain information that the symbiont needs to carry out the 
function. 

By calling SMB$READ_MESSAGE, the symbiont reads the request and writes 
the message items into the specified buffer. The symbiont then obtains the 
individual message items by calling the SMB$READ_MESSAGE_ITEM routine. 

Each message item consists of a code that identifies the information the item 
represents, and the item itself. For example, the SMB$K_JOB_NAME code tells 
the symbiont that the item specifies a job’s name. 
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The number of items in a request varies with each type of request. Therefore, 
you must call SMB$READ_MESSAGE_ITEM repeatedly for each request to 
ensure that all message items are read. Each time SMB$READ_MESSAGE_ 
ITEM reads a message item, it updates the value in the longword specified by 
the context argument. SMB$READ_MESSAGE_ITEM returns the code SMB$. 
NOMOREITEMS after it has read the last message item. 

The following table shows the message items that can be delivered with each 
request: 


Request Message Item 

SMBMSG$K_START_TASK SMBMSG$K_ACCOUNT_NAME 

SMBMSG$K_AFTER_TIME 

SMBMSG$K_BOTTOM_MARGIN 

SMBMSG$K_CHARACTERISTICS 

SMBMSG$K_CHECKPOINT_DATA 

SMBMSG$K_ENTRY_NUMBER 

SMBMSG$K_FILE_COPIES 

SMBMSG$K_FILE_COUNT 

SMBMSG$K_FILE_IDENTIFICATION 

SMBMSG$K_FILE_SETUP_MODULES 

SMBMSG$K_FILE_SPECIFICATION 

SMBMSG$K_FIRST_PAGE 

SMBMSG$K_FORM_LENGTH 

SMBMSG$K_FORM_NAME 

SMBMSG$K_FORM_SETUP_MODULES 

SMBMSG$K_FORM_WIDTH 

SMBMSG$K_JOB_COPIES 

SMBMSG$K_JOB_COUNT 

SMBMSG$K_JOB_NAME 

SMBMSG$K_JOB_RESET_MODULES 

SMBMSG$K_LAST_PAGE 

SMBMSG$K_LEFT_MARGIN 

SMBMSG$K_MESSAGE_VECTOR 

SMBMSG$K_NOTE 

SMBMSG$K_PAGE_SETUP_MODULES 

SMBMSG$K_PARAMETER_1 


SMBMSG$K_PARAMETER_8 

SMBMSG$K_PRINT_CONTROL 

SMBMSG$K_SEPARATION_CONTROL 

SMBMSG$K_REQUEST_CONTROL 
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Request 

Message Item 

SMBMSG$K_STOP_TASK 

SMBMSG$K_PRIORITY 

SMBMSG$K_QUEUE 

SMBMSG$K_RIGHT_MARGIN 

SMBMSG$K_TIME_QUEUED 

SMBMSG$K_TOP_MARGIN 

SMBMSG$K_UIC 

SMBMSG$K_USER_NAME 

SMBMSG$K_STOP_CONDITION 

SMBMSG$K_PAUSE_TASK 

None 

SMBMSG$K_RESUME_TASK 

SMBMSG$K_ALIGNMENT_PAGES 

SMBMSG$K_START_STREAM 

SMBMSG$K_RELATIVE_PAGE 

SMBMSG$K_REQUEST_CONTROL 

SMBMSG$K_SEARCH_STRING 

SMBMSG$K_DEVICE_NAME 

SMBMSG$K_STOP_STREAM 

SMBMSG$K_EXECUTOR_QUEUE 

SMBMSG$K_JOB_RESET_MODULES 

SMBMSG$K_LIBRARY_SPECIFICATION 

None 

smbmsg$k_reset_stream 

None 


The following list enumerates each item code. For each code, the list describes 
the contents of the message item identified by the code and whether the code 
identifies an item sent from the job controller to the symbiont or from the 
symbiont to the job controller. 

Many of the codes described are specifically oriented toward print symbionts. The 
symbiont you implement, which might not print files or serve an output device, 
need not recognize all these codes. In addition, it need not respond in the same 
way as the print symbiont to the codes it recognizes. The descriptions in the list 
describe how the standard print symbiont (PRTSMB.EXE) processes these items. 

_ Note _ 

Because new codes might be added in the future, you should write your 
symbiont so that it ignores codes it does not recognize. 


Codes for Message Items 

SMBMSG$K_ACCOUNT_NAME 

This code identifies a string containing the name of the account to be charged for 
the job, that is, the account of the process that submitted the print job. 

SMBMSG$K_AFTER_TIME 

This code identifies a 64-bit, absolute-time value specifying the system time after 
which the job controller can process this job. 
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SMBMSG$K_ALIGNMENT_PAGES 

This code identifies a longword specifying the number of alignment pages that the 
symbiont is to print. 

SMBMSG$K_BOTTOM_MARGIN 

This code identifies a longword containing the number of lines to be left blank at 
the bottom of a page. 

The symbiont inserts a formfeed character into the output stream if it determines 
that all of the following conditions are true: 

• The number of lines left at the bottom of the page is equal to the value in 
SMBMSG$K_BOTTOM_MARGIN 

• Sending more data to the printer to be output on this page would cause 
characters to be printed within this bottom margin of the page 

• The /FEED qualifier was specified with the PRINT command that caused the 
symbiont to perform this task 

(Linefeed, formfeed, carriage-return, and vertical-tab characters in the output 
stream are collectively known as embedded carriage control.) 

SMBMSG$K_CHARACTERISTICS 

This code identifies a 16-byte structure specifying characteristics of the job. A 
detailed description of the format of this structure is contained in the description 
of the QUI$_CHARACTERISTICS code in the SYS$GETQUI system service in 
the OpenVMS System Services Reference Manual. 

SMBMSG$K_DEVICE_NAME 

This code identifies a string that is the name of the device to which the symbiont 
is to send data. The symbiont interprets this information. The name need not 
be the name of a physical device, and the symbiont can interpret this string as 
something other than the name of a device. 

SMBMSG$K_ENTRY_NUMBER 

This code identifies a longword containing the number that the job controller 
assigned to the job. 

SMBMSG$K_EXECUTOR_QUEUE 

This code identifies a string that is the name of the queue on which the symbiont 
stream is to be started. 

SMBMSG$K_FILE_COPIES 

This code identifies a longword containing the number of copies of the file that 
were requested. 

SMBMSG$K_FILE_COUNT 

This code identifies a longword that specifies, out of the number of copies 
requested for this job (SMBMSG$K_FILE_COPIES), the number of the copy of 
the file currently printing. 

SMBMSG$K_FILEJDENTIFICATION 

This code identifies a 28-byte structure identifying the file to be processed. This 
structure consists of the following three file-identification fields in the RMS NAM 
block: 

1. The 16-byte NAM$T_DVI field 


SMB-24 





Symbiont/Job Controller Interface (SMB) Routines 

SMB$READ_MESSAGEJTEM 


2. The 6-byte NAM$W_FID field 

3. The 6-byte NAM$W_DID field 

These fields occur consecutively in the NAM block in the order listed. 

SMBMSG$K_FILE_SETUP_MODULES 

This code identifies a string specifying the names (separated by commas) of one or 
more text modules that the symbiont should copy from the library into the output 
stream before processing the file. 

SMBMSG$K_FILE_SPECIFICATION 

This code identifies a string specifying the name of the file that the symbiont is to 
process. This file name is formatted as a standard RMS file specification. 

SMBMSG$K_FIRST_PAGE 

This code identifies a longword containing the number of the page at which 
the symbiont should begin printing. The job controller sends this item to the 
symbiont. When not specified, the symbiont begins processing at page 1. 

SMBMSG$K_FORM_LENGTH 

This code identifies a longword value specifying the length (in lines) of the 
physical form (the paper). 

SMBMSG$K_FORM_NAME 

This code identifies a string specifying the name of the form. 

smbmsg$k_form_setup_modules 

This code identifies a string consisting of the names (separated by commas) of one 
or more modules that the symbiont should copy from the device-control library 
before processing the file. 

SMBMSG$K_FORM_WIDTH 

This code identifies a longword specifying the width (in characters) of the print 
area on the physical form (the paper). 

SMBMSG$K_JOB_COPIES 

This code identifies a longword specifying the requested number of copies of the 
job. 

SMBMSG$K_JOB_COUNT 

This code identifies a longword specifying, out of the number of copies requested 
(SMBMSG$K_JOB_COPIES), the number of the copy of the job currently 
printing. 

SMBMSG$K_JOB_NAME 

This code identifies a string specifying the name of the job. 

SMBMSG$K_JOB_RESET_MODULES 

This code identifies a string specifying a list of one or more modules names 
(separated by commas) that the symbiont should copy from the device- 
control library after processing the task. These modules can be used to reset 
programmable devices to a known state. 
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SMBMSG$K_LAST_PAGE 

This code identifies a longword specifying the number of the last page that the 
symbiont is to print. When not specified, the symbiont attempts to print all the 
pages in the file. 

SMBMSG$K_LEFT_MARGIN 

This code identifies a longword specifying the number of spaces to be inserted at 
the beginning of each line. 

SMBMSG$K_LIBRARY_SPECIFICATION 

This code identifies a string specifying the name of the device-control library. 

SMBMSG$K_MESSAGE_VECTOR 

This code identifies a vector of longword condition codes, each of which contains 
information about the job to be printed. 

When LOGINOUT cannot open a log file for a batch job, a code in the message 
vector specifies the reason for the failure. The job controller does not send the 
SMBMSG$K_FILE_IDENTIFICATION item if it has detected such a failure 
but instead sends the message vector, which the symbiont prints, along with a 
message stating that there is no file to print. 

SMBMSG$K_NOTE 

This code identifies a user-supplied string that the symbiont is to print on the 
job-fiag page and on the file-fiag page. 

SMBMSG$K_PAGE_SETUP_MODULES 

This code identifies a string consisting of the names (separated by commas) of one 
or more modules that the symbiont should copy from the device-control library 
before printing each page. 

SMBMSG$K_PARAMETER_1 through SMBMSG$K_PARAMETER_8 

Each of these eight codes identifies a user-supplied string. Both the semantics 
and syntax of each string are determined by the user-defined symbiont. The 
OpenVMS-supplied symbiont makes no use of these eight items. 

SMBMSG$K_PRINT_CONTROL 

This code identifies a longword bit vector, each bit of which supplies information 
that the symbiont is to use in controlling the printing of the file. 


Symbol Description 

SMBMSG$V_DOUBLE_SPACE The symbiont uses a double-spaced 

format; it skips a line after each line 
it prints. 

SMBMSG$V_NORECORD_BLOCKING The symbiont performs single record 

output, issuing a single output record 
for each input record. 

SMBMSG$V_PAGE_HEADER The symbiont prints a page header 

at the top of each page. 
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Symbol Description 


SMBMSG$V_PAGINATE 

SMBMSG$V_PASSALL 

SMBMSG$V_RECORD_BLOCKING 

SMBMSG$V_SEQUENCED 

SMBMSG$V_SHEET_FEED 

SMBMSG$V_TRUNCATE 

SMBMSG$V_WRAP 


The symbiont inserts a formfeed 
character when it detects an attempt 
to print in the bottom margin of the 
current form. 

The symbiont prints the file 
without formatting and bypasses 
all formatting normally performed. 
Furthermore, the symbiont outputs 
the file without formatting, by 
causing the output QIO to suppress 
formatting by the driver. 

The symbiont performs record 
blocking, buffering output to the 
device. 

This bit is reserved by Digital. 

The symbiont pauses the queue after 
each page it prints. 

The symbiont truncates input lines 
that exceed the right margin of the 
current form. 

The symbiont wraps input lines that 
exceed the right margin, printing the 
additional characters on a new line. 


SMBMSG$K_PRIORITY 

This code identifies a longword specifying the priority this job has in the queue in 
which it is entered. 

SMBMSG$K_QUEUE 

This code identifies a string specifying the name of the queue in which this job 
is entered. When generic queues are used, this item specifies the name of the 
generic queue, and the SMBMSG$K_EXECUTOR item specifies the name of the 
device queue or the server queue. 

SMBMSG$K_RELATIVE_PAGE 

This code identifies a signed, longword value specifying the number of pages that 
the symbiont is to move forward (positive value) or backward (negative value) 
from the current position in the file. 

SMBMSG$K_REQUEST_CONTROL 

This code identifies a longword bit vector each bit of which specifies information 
that the symbiont is to use in processing the request that the job controller is 
making. 
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Symbol Description 


SMBMSG$V_ALIGNMENT_MASK 

SMBMSG$V_PAUSE_COMPLETE 

SMBMSG$V_RESTARTING 

SMBMSG$V_TOP_OF_FILE 


The symbiont is to replace all 
alphabetic characters with the letter 
X, and all numeric characters with 
the number 9. Other characters 
(punctuation, carriage control, 
and so on) are left unchanged. 

This bit is ordinarily specified in 
connection with the SMBMSG$K_ 
ALIGNMENT_PAGES item. 

The symbiont is to pause when it 
completes the current request. 

Indicates that this job was previously 
interrupted and requeued, and is 
now restarting. 

The symbiont is to rewind the input 
file before it resumes printing. 


SMBMSG$K_RIGHT_MARGIN 

This code identifies a longword specifying the number of character positions to 
be left empty at the end of each line. When the right margin is exceeded, the 
symbiont truncates the line, wraps the line, or continues processing, depending 
on the settings of the WRAP and TRUNCATE bits in the SMBMSG$K_PRINT_ 
CONTROL item. 

SMBMSG$K_SEARCH_STRING 

This code identifies a string containing the value specified in the START/QUEUE 
/SEARCH command. This string identifies the page at which to restart the 
current printing task on a paused queue. 

SMBMSG$K_SEPARATION_CONTROL 

This code identifies a longword bit vector, each bit of which specifies an operation 
that the symbiont is to perform between jobs or between files within a job. The 
$SMBDEF macro defines the following symbols for each bit: 


Symbol 

SMBMSG$V_FILE_BURST 

SMBMSG$V_FILE_FLAG 

SMBMSG$V_FILE_TRAILER 

SMBMSG$V_FILE_TRAILER_ABORT 

SMBMSG$V_FIRST_FILE_OF_JOB 


Description 

The symbiont is to print a file-burst 
page. 

The symbiont is to print a file-fiag 
page. 

The symbiont is to print a file-trailer 
page. 

The symbiont is to print a file- 
trailer page when a task completes 
abnormally. 

The current file is the first file 
of the job. When specified with 
SMBMSG$V_LAST_FILE_OF_JOB, 
the current job contains a single file. 
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Symbol Description 


SMBMSG$V_JOB_FLAG 

SMBMSG$V_JOB_BURST 

SMBMSG$V_JOB_RESET 

SMBMSG$V_JOB_RESET_ABORT 

SMBMSG$V_JOB_TRAILER 

SMBMSG$V_JOB_TRAILER_ABORT 

SMBMSG$V_LAST_FILE_OF_JOB 


The symbiont is to print a job-flag 
page. 

The symbiont is to print a job-burst 
page. 

The symbiont is to execute a job-reset 
sequence when the task completes. 

The symbiont is to execute a job-reset 
sequence when a task completes 
abnormally. 

The symbiont is to print a job-trailer 
page. 

The symbiont is to print a job- 
trailer page when a task completes 
abnormally. 

The current file is the last file 
of the job. When specified with 
SMBMSG$V_FIRST_FILE_OF_JOB, 
the current job contains a single job. 


SMBMSG$K_STOP_CONDITION 

This code identifies a longword containing a condition specifying the reason the 
job controller issued a STOP_TASK request. 

SMBMSG$K_TIME_QUEUED 

This code identifies a quadword specifying the time the file was entered into the 
queue. The time is expressed as 64-bit, absolute time. 

SMBMSG$K_TOP_MARGIN 

This code identifies a longword specifying the number of lines that the symbiont 
is to leave blank at the top of each page. PRTSMB inserts linefeeds into the 
output stream after every formfeed until the margin is cleared. 

SMBMSG$K_UIC 

This code identifies a longword specifying the User Identification Code (UIC) of 
the user who submitted the job. 

SMBMSG$K_USER_NAME 

This code identifies a string specifying the name of the user who submitted the 
job. 

Condition Values Returned 

SS$_NORMAL Routine completed successfully. 

SMB$_NOMOREITEMS End of item list reached. 

This routine also returns any condition code returned by the Run-Time Library 
string-handling (STR$) routines. 
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SMB$SEND_TO_JOBCTL—Send Message to Job Controller 

The SMB$SEND_TO_JOBCTL routine is used by your symbiont to send messages 
to the job controller. Three types of message can be sent: request-completion 
messages, task-completion messages, and task-status messages. 

Format 

SMB$SEND_TO_JOBCTL stream [.request] [.accounting] [.checkpoint] 

[.device_status] [.error] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 

Arguments 

stream 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Stream number specifying the stream to which the message refers. The stream 
argument is the address of a longword containing the number of the stream to 
which the message refers. 

request 

OpenVMS usage identifier 
type longword (unsigned) 

access read only 

mechanism by reference 

Request code identifying the request being completed. The request argument is 
the address of a longword containing the code that identifies the request that has 
been completed. 

The code usually corresponds to the code the job controller passed to the symbiont 
by means of a call to SMB$READ_MESSAGE. But the symbiont can also initiate 
task-completion and task-status messages that are not in response to a request. 
(See the DESCRIPTION section.) 

accounting 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 
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Accounting information about a task. The accounting argument is the address 
of a descriptor pointing to the accounting information about a task. Note that 
this structure is passed by descriptor and not by reference. 

The job controller accumulates task statistics into a job-accounting record, which 
it writes to the accounting file when the job is completed. 

The following diagram depicts the contents of the 16-byte structure: 

31_0 

Number of Pages Printed for the Job 


Number of Reads from Disk or Tape 


Number of Writes to the Printing Device 


Unused 


ZK-2012-GE 


checkpoint 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Checkpoint data about the currently executing task. The checkpoint argument 
is the address of the descriptor that points to checkpointing information that 
relates to the status of a task. When the symbiont sends this information to 
the job controller, the job controller saves it in the queue database. When a 
restart-from-checkpoint request is executed for the queue, the job controller 
retrieves the checkpointing information from the queue database and sends it to 
the symbiont in the SMBMSG$K_CHECKPOINT_DATA item that accompanies a 
SMBMSG$K_START_TASK request. 

Print symbionts can use the checkpointing information to reposition the input 
file to the point corresponding to the page being output when the last checkpoint 
was taken. Other symbionts might use checkpoint information to specify restart 
information for partially completed tasks. 

_ Note _ 

Because each checkpoint causes information to be written into the 
job controller’s queue database, taking a checkpoint incurs significant 
overhead. Use caution in regard to the size and frequency of checkpoints. 
When determining how often to checkpoint, weigh processor and file¬ 
system overhead against the convenience of restarting. 


device_status 

OpenVMS usage 

type 

access 

mechanism 


longword_unsigned 
longword (unsigned) 
read only 
by reference 


SMB-31 


Symbiont/Job Controller Interface (SMB) Routines 
SMB$SEND_TO_JOBCTL 


Status of the device served by the symbiont. The device_status argument is the 
address of a longword passed to the job controller, which contains the status of 
the device to which the symbiont is connected. 

This longword contains a longword bit vector, each bit of which specifies device¬ 
status information. Each programming language provides an appropriate 
mechanism for defining these device-status bits. The following table describes 
each bit: 


Device Status Bit 


Description 


SMBMSG$V_LOWERCASE 

SMBMSG$V_PAUSE_TASK 


SMBMSG$V_REMOTE 

SMBMSG$V_SERVER 

SMBMSG$V_STALLED 

SMBMSG$V_STOP_STREAM 

SMBMSG$V_TERMINAL 

SMBMSG$V_UNAVAILABLE 


The device to which the symbiont is connected 
supports lowercase characters. 

The symbiont sends this message to inform 
the job controller that the symbiont has 
paused on its own initiative. 

The device is connected to the symbiont by 
means of a modem. 

The symbiont is not connected to a device. 
Symbiont processing is temporarily stalled. 

The symbiont requests that the job controller 
stop the queue. 

The symbiont is connected to a terminal. 

The device to which the symbiont is connected 
is not available. 


error 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Condition codes returned by the requested task. The error argument is the 
address of a vector of longword condition codes. The first longword contains the 
number of longwords following it. 

If the low bit of the first condition code is clear, the job controller aborts 
further processing of the job. Output of any remaining files, copies of files, or 
copies of the job is canceled. In addition, the job controller saves up to three 
condition values in the queue database. The first condition value is included 
in the job-accounting record that is written to the system’s accounting file 
(SYS$MANAGER:ACCOUNTNG.DAT). 


Description 

The symbiont uses the SMB$SEND_TO_JOBCTL routine to send messages to the 
job controller. 

Most messages the symbiont sends to the job controller are responses to requests 
made by the job controller. These responses inform the job controller that the 
request has been completed, either successfully or with an error. When the 
symbiont sends the message, it usually indicates that the request has been 
completed. 
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In such messages, the request argument corresponds to the function code of 
the request that has been completed. Thus, if the job controller sends a request 
using the SMBMSG$K_START_TASK code, the symbiont responds by sending 
a SMB$SEND_TO_JOBCTL message using SMBMSG$K_START_TASK as the 
request argument. 

The responses to some requests use additional arguments to send more 
information in addition to the request code. The following table shows which 
additional arguments are allowed in response to each different request: 


Request 

Arguments 

SMBMSG$K_START_STREAM 

request 

device_status 


error 

SMBMSG$K_STOP_STREAM 

request 

SMBMSG$K_RESET_STREAM 

request 

SMBMSG$K_START_TASK 

request 

SMBMSG$K_PAUSE_TASK 

request 

smbmsg$k_resume_task 

request 

SMBMSG$K_STOP_TASK 

request 
error^ 

^This is usually the value specified in the SMBMSG$K_STOP_CONDITION item that was sent by the 
job controller with the SMBMSG$K_STOP_TASK request. 


In addition to responding to requests from the job controller, the symbiont can 
send other messages to the job controller. If the symbiont sends a message that is 
not a response to a request, it uses either the SMBMSG$K_TASK_COMPLETE or 
SMBMSG$K_TASK_STATUS code. Following are the additional arguments that 
you can use with the messages identified by these codes: 


Code 

Arguments 

SMBMSG$K_TASK_COMPLETE 

request 


accounting 


error 

SMBMSG$K_TASK_STATUS 

request 


checkpoint 


device_status 




The symbiont uses the SMBMSG$K_TASK_STATUS message to update the 
job controller on the status of a task during the processing of that task. The 
checkpoint information passed to the job controller with this message permits 
the job controller to restart an interrupted task from an appropriate point. The 
device-status information permits the symbiont to report changes in device’s 
status (device stalled, for example). 

The symbiont can use the SMBMSG$K_TASK_STATUS message to request 
that the job controller send a stop-stream request. It does this by setting the 
stop-stream bit in the device-status argument. 
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The symbiont can also use the SMBMSG$K_TASK_STATUS message to notify 
the job controller that the symbiont has paused in processing a task. It does so 
by setting the pause-task bit in the device-status argument. 

The symbiont uses the SMBMSG$K_TASK_COMPLETE message to signal the 
completion of a task. Note that, when the symbiont receives a START_TASK 
request, it responds by sending a SMB$SEND_TO_JOBCTL message with 
SMBSMG$K_START_TASK as the request argument. This response means that 
the symbiont has started the task; it does not mean the task has been completed. 
When the symbiont has completed a task, it sends a SMB$SEND_TO_JOBCTL 
message with SMBMSG$K_TASK_COMPLETE as the request argument. 

Optionally, the symbiont can specify accounting information when sending a 
task-completion message. The accounting statistics accumulate to give a total for 
the job when the job is completed. 

Also, if the symbiont is aborting the task because of a symbiont-detected error, 
you can specify up to three condition values in the error argument. Aborting a 
task causes the remainder of the job to be aborted. 

Condition Values Returned 

SS$_NORMAL Routine completed successfully. 

This routine also returns any condition value returned by the $QIO system 
service and the LIB$GET_VM routine. 
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The SOR routines allow you to integrate a sort or merge operation into a program 
application. Using these callable routines, you can process some records, sort or 
merge them, and then process them again. 


14.1 Introduction to SOR Routines 


The following SOR routines are available for use in a sort or merge operation: 


SOR$BEGIN_MERGE 

SOR$BEGIN_SORT 

SOR$DTYPE 

SOR$END_SORT 

SOR$PASS_FILES 

SOR$RELEASE_REC 

SOR$RETURN_REC 

SOR$SORT_MERGE 

SOR$SPEC_FILE 

SOR$STAT 


Sets up key arguments and performs the merge. This is the 
only routine unique to MERGE. 

Initializes sort operation by passing key information and sort 
options. This is the only routine unique to SORT. 

Defines a key data-type that is not normally supported by 
SORT/MERGE. 

Performs cleanup functions, such as closing files and 
releasing memory. 

Passes names of input and output files to SORT or MERGE; 
must be repeated for each input file. 

Passes one input record to SORT or MERGE; must be called 
once for each record. 

Returns one sorted or merged record to a program; must be 
called once for each record. 

Sorts the records. 

Passes a specification file or specification text. A call to this 
routine must precede all other calls to the SOR routines. 

Returns a statistic about the sort or merge operation. 


You can call these SOR routines from any language that supports the OpenVMS 
Calling Standard. Note that the application program should declare referenced 
constants and return status symbols as external symbols; these symbols will be 
resolved upon linking with utility shareable image. 

After being called, each of these routines performs its function and returns control 
to a program. It also returns a 32-bit condition code value indicating success or 
error, which a program can test to determine success or failure conditions. 


14.1.1 Arguments to SOR Routines 

For a sort operation, the arguments to the SOR routines provide SORT with file 
specifications, key information, and instructions about the sorting process. For a 
merge operation, the arguments to the SOR routines provide MERGE with the 
number of input files, input and output file specifications, record information, 
key information, and input routine information. To perform sort or merge 
operations, you must pass key information (key_buffer argument) to either 
the SOR$BEGIN_SORT or SOR$BEGIN_MERGE routine. The key^uffer 
argument is passed as an array of words. The first word of the array contains the 
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number of keys to be used in the sort or merge. Each block of four words that 
follows describes one key (multiple keys are listed in order of their priority): 

• The first word of each block describes the key data type. 

• The second word determines the sort or merge order (0 for ascending, 1 for 
descending). 

• The third word describes the relative offset of the key (beginning at position 

0 ). 

• The fourth word describes the length of the key in bytes. 

There are both mandatory and optional arguments. The mandatory arguments 
appear first in the argument list. You must specify all arguments in the order in 
which they are positioned in the argument list, separating each with a comma. 
Pass a zero by value to specify any optional arguments that you are omitting 
from within the list. You can end the argument list any time after specifying all 
the mandatory and desired optional arguments. 

14.1.2 Interfaces to SOR Routines 

You can submit data to the SOR routines as complete files or as single records. 
When your program submits one or more files to SORT or MERGE, which then 
creates one sorted or merged output file, you are using the file interface. When 
your program submits records one at a time and then receives the ordered records 
one at a time, you are using the record interface. 

You can combine the file interface with the record interface by submitting files 
on input and receiving the ordered records on output or by releasing records on 
input and writing the ordered records to a file on output. Combining the two 
interfaces provides greater flexibility. If you use the record interface on input, 
you can process the records before they are sorted; if you use the record interface 
on output, you can process the records after they are sorted. 

The SOR routines used and the order in which they are called depend on the type 
of interface used in a sorting or merging operation. The following sections detail 
the calling sequence for each of the interfaces. Note, however, that if you use the 
SOR$STAT routine, it must be called before any other SOR routine. 

14.1.2.1 Sort Operation Using File Interface 

For a sort operation using the file interface, pass the input and output file 
specifications to SORT by calling SOR$PASS_FILES. You must call SOR$PASS_ 
FILES for each input file specification. Pass the output file specification in the 
first call. If no input files are specified before the call to SOR$BEGIN_SORT, the 
record interface is used for input; if no output file is specified, the record interface 
is used for output. 

Next, call SOR$BEGIN_SORT to pass instructions about keys and sort options. 
At this point, you must indicate whether you want to use your own key 
comparison routine. SORT automatically generates a key comparison routine 
that is efficient for key data types; however, you might want to provide your own 
comparison routine to handle special sorting requirements. (For example, you 
might want names beginning with “Me” and “Mac” to be placed together.) If you 
use your own key comparison routine, you must pass its address with the user_ 
compare argument. 
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Call SOR$SORT_MERGE to execute the sort and direct the sorted records to the 
output file. Finally, call SOR$END_SORT to end the sort and release resources. 
The SOR$END_SORT routine can be called at any time to abort a sort or to 
merge and release all resources allocated to the sort or merge process. 

14.1.2.2 Sort Operation Using Record Interface 

For a sort operation using the record interface, first call SOR$BEGIN_SORT. As 
in the file interface, this routine sets up work areas and passes arguments that 
define keys and sort options. Note that, if you use the record interface, you must 
use a record-sorting process (not a tag, address, or index process). 

Next, call SOR$RELEASE_REC to release a record to SORT. Call 
SOR$RELEASE_REC once for each record to be released. After all records 
have been passed to SORT, call SOR$SORT_MERGE to perform the sorting. 

After the sort has been performed, call SOR$RETURN_REC to return a record 
from the sort operation. Call this routine once for each record to be returned. 
Finally, call the last routine, SOR$END_SORT, to complete the sort operation 
and release resources. 

14.1.2.3 Merge Operation Using Fiie interface 

For a merge operation using the file interface, pass the input and output file 
specifications to MERGE by calling SOR$PASS_FILES. You can merge up to 
10 input files by calling SOR$PASS_FILES once for each file. Pass the file 
specification for the merged output file in the first call. If no input files are 
specified before the call to SOR$BEGIN_MERGE, the record interface is used for 
input; if no output file is specified, the record interface is used for output. 

Next, to execute the merge, call SOR$BEGIN_MERGE to pass key information 
and merge options. At this point, you must indicate whether you want to use 
your own key comparison routine tailored to your data. Finally, call SOR$END_ 
SORT to release resources. 

14.1.2.4 Merge Operation Using Record Interface 

For a merge operation using the record interface, first call SOR$BEGIN_MERGE. 
As in the file interface, this routine passes arguments that define keys and merge 
options. It also issues the first call to the input routine, which you must create, 
to begin releasing records to the merge. 

Next, call SOR$RETURN_REC to return the merged records to your program. 
You must call this routine once for each record to be returned. SOR$RETURN_ 
REC continues to call the input routine. MERGE, unlike SORT, does not need 
to hold all the records before it can begin returning them in the desired order. 
Releasing, Merging, and Returning of records all take place in this phase of the 
merge. 

Finally, after all the records have been returned, call the last routine, SOR$END_ 
SORT, to clean up and release resources. 

14.1.3 Reentrancy 

The SOR routines are reentrant; that is, a number of sort or merge operations 
can be active at the same time. Thus, a program does not need to finish one sort 
or merge operation before beginning another. For example, reentrancy lets you 
perform multiple sorts on a file such as a mailing list and to create several output 
files, one with the records sorted by name, another sorted by state, another sorted 
by zip code, and so on. 
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The context argument, which can optionally be passed with any of the SOR 
routines, distinguishes among multiple sort or merge operations. When using 
multiple sort or merge operations, the context argument is required. On the first 
call, the context longword must be zero. It is then set (by SORT/MERGE) to a 
value identifying the sort or merge operation. Additional calls to the same sort 
or merge operation must pass the same context longword. The SOR$END_SORT 
routine clears the context longword. 

14.2 Examples of Using SOR Routines 

This section provides examples of using the SOR utilities for various operations 
including the following: 

• Example 14-1 is a DEC Fortran program that demonstrates a merge 
operation using a record interface. 

• Example 14—2 is a DEC Fortran program that demonstrates a sort operation 
using a file interface on input and a record interface on output. 

• Example 14-3 is a DEC Pascal program that demonstrates a merge operation 
using a file interface. 

• Example 14-4 is a DEC Pascal program that demonstrates a sort operation 
using a record interface. 


Example 14-1 Using SOR Routines to Perform a Merge Using Record Interface in a DEC 
Fortran Program 


FORTRAN Program 


C... 

C... This program demonstrates the FORTRAN calling sequences 
C... for the merge record interface. 

C... 

C 

C THE INPUT FILES ARE LISTED BELOW. 

C 

C INFILE1.DAT 

C 

C 1 BBBBBBBBBB REST OF DATA IN RECORD. 

C 2 UUUUUUUUUU REST OF DATA IN RECORD. 

C 

C INFILE2.DAT 

C 

C 1 AAAAAAAAAA REST OF DATA IN RECORD. 

c 2 tttttttttt rest of data in record. 

C 

C INFILE3.DAT 

C 

c 1 tttttttttt rest of data in record. 

C 2 BBBBBBBBBB REST OF DATA IN RECORD. 

C 


END OF RECORD 
END OF RECORD 


END OF RECORD 
END OF RECORD 


END OF RECORD 
END OF RECORD 


(continued on next page) 
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Example 14-1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in a 

DEC Fortran Program 


C FOROUT.DAT 

C 

C 1 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 1 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 1 tTTTTTTTTT rest of data in record.END OF RECORD 

C 2 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 2 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 2 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 

C 

C. 

c 

c 


IMPLICIT INTEGER (A-Z) 

CHARACTER*80 REC 

EXTERNAL READ_REC 
EXTERNAL KOMPAR 
EXTERNAL SS$_ENDOFFILE 

INTEGER*4 SOR$BEGIN_MERGE 
INTEGER*4 SOR$RETURN_REC 
INTEGER*4 SOR$END_SORT 
INTEGER*4 ISTAT 
INTEGER*4 LENGTH 
INTEGER*2 LRL 

LOGICAL*! ORDER 

DATA ORDER,LRL/3,80/ 

C. . . 

C... First open all the input files. 

C... 

OPEN (UNIT=10, FILE='INFILE1.DAT',TYPE='OLD',READONLY, 

* FORM='FORMATTED') 

OPEN (UNIT=11, FILE='INFILE2.DAT',TYPE='OLD',READONLY, 

* FORM='FORMATTED') 

OPEN (UNIT=12, FILE='INFILE3.DAT',TYPE='OLD',READONLY, 

* FORM='FORMATTED') 

C 

C... Open the output file. 

C 

OPEN (UNIT=8, FILE='TEMP.TMP', TYPE='NEW') 

C. . . 

C... Initialize the merge. Pass the merge order, the largest 
C... record length, the compare routine address, and the 
C... input routine address. 

C... 

ISTAT = SOR$BEGIN_MERGE (,LRL,,ORDER, 

* KOMPAR,,READ_REC) 

IF (.NOT. ISTAT) GOTO 10 ! Check for error. 


! A record. 

1 Routine to read a record. 

1 Routine to compare records. 
1 System end-of-file value 

! SORT/MERGE function names 


! storage for SORT/MERGE function value 
! length of the returned record 
! Longest Record Length (LRL) 

! #files to merge (merge order) 

! Order of the merge=3,LRL=80 


(continued on next page) 
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Example 14-1 (Cent.) Using SOR Routines to Perform a Merge Using Record Interface in a 

DEC Fortran Program 


c... 

C... Now loop getting merged records. SOR$RETURN__REC will 
C... call READ_REC when it needs input. 

C... 

5 ISTAT = SOR$RETURN_REC (REC, LENGTH) 

IF (ISTAT .EQ. %LOC(SS$_ENDOFFILE)) GO TO 30 I Check for end of file. 
IF (.NOT. ISTAT) GO TO 10 ! Check for error. 

WRITE(8,200) REC ! Output the record. 

200 FORMAT(' ',k) 

GOTO 5 ! And loop back. 

C... 

C... Now tell SORT that we are all done. 

C... 

30 ISTAT = SOR$END_SORT() 

IF (.NOT. ISTAT) GOTO 10 1 Check for error. 

CALL EXIT 

C. . . 

C... Here if an error occurred. Write out the error status 
C... and exit. 

C... 

10 WRITE(8,201)ISTAT 

201 FORMAT(' ?ERRORCODE\ 120) 

CALL EXIT 

END 

FUNCTION READ_REC (RECX, FILE, SIZE) 

C. . . 

C... This routine reads a record from one of the input files 
C... for merging. It will be called by SOR$BEGIN_MERGE and by 
C. . . SOR$RETURN_REC. 

C... Parameters: 

C... 

C... RECX.wcp.ds 

C... 

C... 

C... FILE.rl.r 

C... 

C. .. 

C... 

C. .. 

C... LENGTH.wl.r 

C... 

C. . . 

IMPLICIT INTEGER (A-Z) 

PARAMETER MAXFIL=10 

EXTERNAL SS$_ENDOFFILE 
EXTERNAL SS$_NORMAL 

LOGICAL*! FILTAB(MAXFIL) 

CHARACTER* (80) RECX ! MAX LRL =80 

DATA FILTAB/10,11,12,13,14,15,16,17,18,19/ 1 Table of I/O unit numbers. 

READ_REC = %LOC(SS$_ENDOFFILE) ! Give end of file return 

IF (FILE .LT. 1 .OR. FILE .GT. MAXFIL) RETURN 1 if illegal call. 


character buffer to hold the record after 
it is read in. 

indicates which file the record is 
to be read from. 1 specifies the 
first file, 2 specifies the second 
etc. 

is the actual number of bytes in 
the record. This is set by READ_REC. 


! Max number of files. 

! End of file status code. 
! Success status code. 


(continued on next page) 
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Example 14-1 (Cont.) Using SOR Routines to Perform a Merge Using Record Interface in a 

DEC Fortran Program 


100 

READ (FILTAB(FILE), 100, ERR=75, 
FORMAT(A) 

END=50) RECX 

1 Read the record. 


READ REC = %L0C(SS$ NORMAL) 

SIZE = LEN (RECX) 

RETURN 

1 Return 
! Return 

success 
size of 

code. 

record. 

c... 

50 

Here if end of file. 

READ_REC = %LOC(SS$__ENDOFFILE) 

! Return 

"end of 

file" code 


RETURN 


C... Here if error while reading 

75 READ_REC = 0 

SIZE = 0 
RETURN 
END 

FUNCTION KOMPAR (REC1,REC2) 

C. . . 

C... This routine compares two records. It returns -1 

C... if the first record is smaller than the second, 

C... 0 if the records are equal, and 1 if the first record 

C... is larger than the second. 

C... 

PARAMETER KEYSIZ=10 

IMPLICIT INTEGER (A-Z) 

LOGICAL*! RECl(KEYSIZ),REC2(KEYSIZ) 

DO 20 I=1,KEYSIZ 

KOMPAR = RECl(I) - REC2(I) 

IF (KOMPAR .NE. 0) GOTO 50 

20 CONTINUE 

RETURN 

50 KOMPAR = ISIGN (1, KOMPAR) 

RETURN 

END 


Exampie 14-2 Using SOR Routines to Sort Using Mixed Interface in a DEC Fortran Program 

Program 


PROGRAM CALLSORT 
C 
C 

C This is a sample FORTRAN program that calls the SOR 

C routines using the file interface for input and the 

C record interface for output. This program requests 

C a record sort of the file 'R010SQ.DAT' and writes 

C the records to SYS$OUTPUT. The key is an 80-byte 

C character ascending key starting in position 1 of 

C each record. 


(continued on next page) 
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Example 14-2 (Cent.) Using SOR Routines to Sort Using Mixed Interface in a DEC Fortran 

Program 

c 

C A short version of the input and output files follows: 


C 

C Input file R010SQ.DAT 

C 1 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 2 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 1 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 2 tTTTTTTTTT rest of data IN RECORD.END OF RECORD 

C 1 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 2 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 1 QQQQQQQQQQ REST OF DATA IN RECORD.END OF RECORD 

C 2 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 1 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 2 QQQQQQQQQQ REST OF DATA IN RECORD.END OF RECORD 

C 

C Output file SYS$OUTPUT 

C 

C 1 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 1 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 1 QQQQQQQQQQ REST OF DATA IN RECORD.END OF RECORD 

C 1 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 1 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 

C 2 AAAAAAAAAA REST OF DATA IN RECORD.END OF RECORD 

C 2 BBBBBBBBBB REST OF DATA IN RECORD.END OF RECORD 

C 2 QQQQQQQQQQ REST OF DATA IN RECORD.END OF RECORD 

C 2 TTTTTTTTTT REST OF DATA IN RECORD.END OF RECORD 

C 2 UUUUUUUUUU REST OF DATA IN RECORD.END OF RECORD 


C 

C--— 

c 

C Define external functions and data. 

C 

CHARACTER*80 RECBUF 

CHARACTER*10 INPUTNAME !Input file name 

INTEGER*2 KEYBUF{5) !Key definition buffer 

INTEGER*4 SOR$PASS_FILES ISORT function names 

INTEGER*4 SOR$BEGIN_SORT 

INTEGER*4 SOR$SORT_MERGE 

INTEGER*4 SOR$RETURN_REC 

INTEGER*4 SOR$END_SORT 

INTEGER*4 ISTATUS !Storage for SORT function value 

EXTERNAL SS$ ENDOFFILE 

EXTERNAL DSC'?K_DTYPE_T 

EXTERNAL SOR$GK_RECORD 

INTEGER*4 SRTTYPE 

C 

C Initialize data — first the file names, then the key buffer for 

C one 80-byte character key starting in position 1, 3 work files, 

C and a record sort process. 

C 

DATA INPUTNAME/'ROIOSQ.DAT'/ 

KEYBUF(l) = 1 

KEYBUF(2) = %LOC(DSC$K_DTYPE_T) 

KEyBUF(3) = 0 
KEYBUF(4) = 0 
KEYBUF(5) = 80 

SRTTYPE = %LOC(SOR$GK_RECORD) 

(continued on next page) 
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Example 14-2 (Cont.) Using SOR Routines to Sort Using Mixed Interface in a DEC Fortran 

Program 

c 

C Call the SORT — each call is a function. 

C 

C 

C Pass SORT the file names. 

C 

ISTATUS = SOR$PASS_FILES(INPUTNAME) 

IF (.NOT. ISTATUS) GOTO 10 
C 

C Initialize the work areas and keys. 

C 

ISTATUS = SOR$BEGIN__SORT (KEYBUF ,,,,,, SRTTYPE, %REF ( 3 ) ) 

IF (.NOT. ISTATUS) GOTO 10 
C 

C Sort the records. 

C 

ISTATUS = SOR$SORT_MERGE( ) 

IF (.NOT. ISTATUS) GOTO 10 
C 

C Now retrieve the individual records and display them. 

C 

5 ISTATUS = SOR$RETURN_REC(RECBUF) 

IF (.NOT. ISTATUS) GOTO 6 
ISTATUS = LIB$PUT_OUTPUT(RECBUF) 

GOTO 5 

6 IF (ISTATUS .EQ. %LOC(SS$_ENDOFFILE)) GOTO 7 
GOTO 10 

C 

C Clean up the work areas and files. 

C 

7 ISTATUS = SOR$END_SORT() 

IF (.NOT. ISTATUS) GOTO 10 
STOP 'SORT SUCCESSFUL' 

10 STOP 'SORT UNSUCCESSFUL' 

END 


Exampie 14-3 Using SOR Routines to Merge Three Input Files in a DEC Pascai Program 

Program 

(* This program merges three input files, (IN_FILE.DAT, 

IN_FILE2.DAT IN_FILE3.DAT), and creates one merged output file. *) 

program mergerecs( output, in_filel, in_file2, in_file3, out_file ); 

CONST 

SS$_NORMAL = 1; 

SS$_ENDOFFILE = %X870; 

SOR$GK_RECORD = 1; 

SOR$M_STABLE = 1; 

SOR$M_SEQ_CHECK = 4; 

SOR$M_SIGNAL = 8; 

DSC$K_DTYPE_T = 14; 


(continued on next page) 
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14.2 Examples of Using SOR Routines 


Example 14-3 (Cont.) Using SOR Routines to Merge Three Input Files in a DEC Pascal 

Program 

TYPE 

$UBYTE = [BYTE] 0..255; 

$UWORD = [WORD] 0..65535; 

const 

num__of_keys = 1; 

merge_order = 3; 

Irl = 131; 

ascending = 0; 

descending = 1; 

type 

key_buffer_block= 
packed record 
key_type: $uword; 

key_order: $uword; 

key_offset: $uword; 

key_length: $uword; 

end; 

key_buf fer_type= 
packed record 
key_count: $uword; 

blocks; packed array[ 1. .num__of_keys] of key_buffer_block; 

end; 

record__buffer = packed array[ 1..Irl] of char; 

record__buf fer__descr = 
packed record 
length: $uword; 
dummy: $uword; 
addr: ^record_buffer; 

end; 

var 

in__filel, 

in_file2, 

in_file3, 

out^file; text; 
key_buffer; key_buffer_type; 
rec_buffer: record_buffer; 
rec_length: $uword; 
status; integer; 

i: integer; 

function sor$begin_merge( 

var buffer: key_buffer_type; 

Irl; $uword; 

mrg_options: integer; 

merge__order: $ubyte; 

%immed cmp_rtn: integer ;= 0; 

%immed eql_rtn: integer := 0; 

%immed [unbound] function 
read_record( 

var rec; record_buffer_descr; 

var filenumber: integer; 
var recordsize: $uword): integer 
); integer; extern; 

(continued on next page) 
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Example 14-3 (Cent.) Using SOR Routines to Merge Three Input Files in a DEC Pascal 

Program 

function sor$return__rec( 

%stdescr rec: record_buffer; 

var rec_size: $uword 

): integer; extern; 

function sor$end_sort: integer; extern; 

procedure sys$exit( %iinined status : integer ); extern; 

function read_record( 

var rec: record_buffer_descr; 

var filenumber: integer; 
var recordsize: $uword 
): integer; 

procedure readone( var filename: text ); 
begin 

recordsize := 0; 
if eof(filename) 
then 

read_record := ss$_endoffile 

else 

begin 

while not eoln(filename) and (recordsize < rec.length) do 
begin 

recordsize := recordsize + 1; 

read(filename,rec.addr^[recordsize]); 

end; 

readln(filename); 
end; 

end; 

begin 

read_record := ss$__normal; 
case filenumber of 

1: readone(in_filel); 

2: readone(in_file2); 

3: readone(in_file3); 
otherwise 

read_record := ss$_endoffile; 

end; 

end; 

procedure initfiles; 
begin 

open( in_filel, 'infilel.dat', old ); 

open( in_file2, 'infile2.dat', old ); 

open( in_file3, 'infile3.dat', old ); 

open( out_file, 'temp.tmp' ); 

reset( in_filel ); 

reset( in_file2 ); 

reset( in_file3 ); 

rewrite( out_file ); 

end; 

procedure error( status : integer ); 
begin 

writeln( 'merge unsuccessful. status=%x', status:8 hex ); 

sys$exit(status); 

end; 


(continued on next page) 
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14.2 Examples of Using SOR Routines 


Example 14-3 (Cent.) Using SOR Routines to Merge Three Input Files in a DEC Pascal 

Program 


begin 

with key_buffer do 
begin 

key_count := 1; 
with blocks[l] do 
begin 

key_type := dsc$k_dtype_t; 
key__order := ascending; 
key_offset ;= 0; 
key_length := 5; 
end; 

end; 

initfiles; 

status := sor$begin_merge( key_buffer, Irl, 
sor$m__seq_check + sor$m_signal, 
merge__order, 0, 0, read_record ); 


repeat 

begin 

rec_length := 0; 

status ;= sor$return_rec( rec__buffer, rec_length ); 

if odd(status) 

then 

begin 

for i ;= 1 to rec__length do write(out__file, rec_buffer[i]); 

writeln(out__file); 

end; 

end 

until not odd(status); 

if status <> ss$__endoffile then error(status); 

status := sor$end_sort; 

if not odd(status) then error(status); 

writeln( 'merge successful.' ); 

end. 


Example 14-4 Using SOR Routines to Sort Records from Two Input Files in a DEC Pascal 
Program 


Pascal Program 

PROGRAM FILETORECORDSORT (OUTPUT,SORTOUT); 

(* This program calls SOR routines to read and sort records from 

two input files, (PASINPUT1.DAT and PASINPUT2.DAT) and to return 
sorted records to this program to be written to the output file, 
(TEMP.TMP). *) 

(* Declarations for external status codes, and data structures, such as 

the types $UBYTE (an unsigned byte) and $UWORD (an unsigned word). *) 


(continued on next page) 
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Example 14-4 (Cent.) Using SOR Routines to Sort Records from Two Input Files in a DEC 

Pascal Program 


CONST 

SS$_NORMAL = 1; 

SS$ ENDOFFILE = %X870; 

SOR^GK_RECORD = 1; 

SOR$M_STABLE = 1; 

SOR$M_SEQ_CHECK = 4; 

SOR$M_SIGNAL = 8; 

DSC$K__DTYPE_T = 14; 

TYPE 

$UBYTE = [BYTE] 0..255; 

$UW0RD = [WORD] 0..65535; 

CONST 

Numberofkeys = 1 ; (* Number of keys for this sort *) 

LRL = 131 ; (* Longest Record Length for output records *) 

(* Key orders *) 

Ascending = 0 ; 

Descending = 1 ; 

TYPE 

Keybufferblock= packed record 

Keytype : $DWORD ; 

Keyorder : $UWORD ; 

Keyoffset : $DWORD ; 

Keylength : $DWORD 
end ; 

(* The keybuffer. Note that the field buffer is a one-component array in 
this program. This type definition would allow a multikeyed sort. *) 

Keybuffer= packed record 

Numkeys : $DWORD ; 

Blocks : packed array[1..Numberofkeys] OF Keybufferblock 
end ; 

(* The record buffer. This buffer will be used to hold the returned 
records from SORT. *) 

Recordbuffer = packed array[1..LRL] of char ; 

(* Name type for input and output files. A necessary fudge for %stdescr 
mechanism. *) 

nametype= packed array[1..13] of char ; 


VAR 

Sortout : text ; ( 
Buffer : Keybuffer ; ( 
Sortoptions : integer ; ( 
Sorttype : $DBYTE ; ( 
Numworkfiles : $DBYTE ; ( 
Status : integer ; ( 
Rec : Recordbuffer ; ( 
Recordlength : $DWORD ; ( 
Inputname: nametype ; ( 
i : integer ; ( 


the output file *) 

the actual keybuffer *) 

flag for sorting options *) 

sorting process *) 

number of work files *) 

function return status code *) 

a record buffer *) 

the returned record length *) 

input file name *) 

loop control variable *) 


(* function and procedure declarations *) 


(continued on next page) 
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14.2 Examples of Using SOR Routines 


Example 14-4 (Cent.) Using SOR Routines to Sort Records from Two Input Files in a DEC 

Pascai Program 

(* Declarations of SORT functions *) 

(* Note that the following SORT routine declarations 

do not use all of the possible routine parameters. *) 

(* The parameters used MUST have all preceding parameters specified, 
however. *) 

FUNCTION SOR$PASS_FILES 

(%STDESCR Inname : nametype ) 

: INTEGER ; EXTERN ; 

FUNCTION SOR$BEGIN_SORT( 

VAR Buffer : Keybuffer ; 

Lrlen ; $UWORD ; 

VAR Sortoptions : INTEGER ; 

%IMMED Filesize : INTEGER ; 

%IMMED Usercompare : INTEGER ; 

%IMMED Userequal : INTEGER ; 

VAR Sorttype : $UBYTE ; 

VAR Numworkfiles : $UBYTE ) 

: INTEGER ; EXTERN ; 

FUNCTION SOR$SORT_MERGE 
; INTEGER ; EXTERN ; 

FUNCTION SOR$RETURN_REC( 

%STDESCR Rec : Recordbuffer ; 

VAR Recordsize : $UWORD ) 

: INTEGER ; EXTERN ; 

FUNCTION SOR$END_SORT 
: INTEGER ; EXTERN ; 

(* End of the SORT function declarations *) 

(* The CHECKSTATUS routine checks the return status for errors. *) 

(* If there is an error, write an error message and exit via sys$exit *) 

PROCEDURE CHECKSTATUS( var status ; integer ) ; 

procedure sys$exit( status : integer ) ; extern ; 

begin (* begin checkstatus *) 

if odd(status) then 
begin 

writeln( ' SORT unsuccessful. Error status = ', status:8 hex ) ; 

SYS$EXIT( status ) ; 
end ; 

end ; (* end checkstatus *) 

(* end function and routine declarations *) 


(continued on next page) 
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Example 14-4 (Cent.) Using SOR Routines to Sort Records from Two Input Files In a DEC 

Pascal Program 


BEGIN (* begin the main routine *) 

(* Initialize data for one 8-byte character key, starting at record 
offset 0, 3 work files, and the record sorting process *) 

Inputname := 'PASINPUT1.DAT' ; 

WITH Buffer DO 
BEGIN 

Numkeys := 1; 

WITH Blocks[l] DO 
BEGIN 

Keytype := DSC$K_DTYPE_T ; (* Use VMS descriptor data types to 

define SORT data types. *) 

Keyorder := Ascending ; 

Keyoffset := 0 ; 

Keylength := 8 ; 

END; 

END; 

Sorttype := SOR$GK_RECORD ; 

Sortoptions := SOR$M__STABLE ; 

Numworkfiles := 3 ; 

(* call the sort routines as a series of functions *) 

(* pass the first filename to SORT *) 

Status := SOR$PASS_FILES( Inputname ) ; 

{* Check status for error. *) 

CHECKSTATUS( Status ) ; 

(* pass the second filename to SORT *) 

Inputname := 'PASINPUT2.DAT' ; 

Status 1 = SOR$PASS_FILES( Inputname ) ; 

(* Check status for error. *) 

CHECKSTATUS( Status ) ; 

(* initialize work areas and keys *) 

Status := SOR$BEGIN_SORT( Buffer, 0, Sortoptions, 0, 0, 0, 

Sorttype, Numworkfiles ) ; 

(* Check status for error. *) 

CHECKSTATUS( Status ) ; 

(* sort the records *) 

Status := SOR$SORT_MERGE ; 

(* Check status for error. *) 

CHECKSTATUS( Status ) ; 

(* Ready output file for writing returned records from SORT. *) 

OPEN( SORTOUT, 'TEMP.TMP' ) ; 

REWRITE( SORTOUT ) ; 

(* Now get the sorted records from SORT. *) 

Recordlength := 0 ; 

REPEAT 

Status := SOR$RETURN_REC( Rec, Recordlength ) ; 


(* Use the global SORT constant to 
define the sort process. *) 

(* Use the global SORT constant to 

define the stable sort option. *) 


(continued on next page) 
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Example 14-4 (Cent.) Using SOR Routines to Sort Records from Two Input Files in a DEC 

Pascal Program 

if odd( Status ) 

then (* if successful, write record to output file. *) 

begin 

for i ;= 1 to Recordlength do 

write( sortout, Rec[i] ) ; (* write each character *) 

writeln (sortout) ; (* end output line *) 

end; 

UNTIL not odd( Status ) ; 

(* If there was just no more data to be returned (eof) continue, otherwise 
exit with an error. *) 
if Status <> SS$__ENDOFFILE then 
CHECKSTATUS( Status ) ; 

(* The sort has been successful to this point. *) 

(* Close the output file *) 

CLOSE( sortout ) ; 

(* clean up work areas and files *) 

Status := SOR$END_SORT ; 

(* Check status for error. *) 

CHECKSTATUS( Status ); 

WRITELN ('SORT SUCCESSFUL') ; 

END. 


14.3 SOR Routines 

The following pages describe the individual SOR routines. 
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SOR$BEGIN_MERGE—Initialize a Merge Operation 

The SOR$BEGIN_MERGE routine initializes the merge operation by opening 
the input and output files and by providing the number of input files, the key 
specifications, and the merge options. 


Format 

SOR$BEGIN_MERGE [key-buffer] [,lrl] [,options] [,merge_order] [,user_compare] 

[,user_equal] [,user_input] [,context] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

key_buffer 

OpenVMS usage vector_word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Array of words describing the keys on which you plan to merge. The key_buffer 
argument is the address of an array containing the key descriptions. 

The first word of this array contains the number of keys described (up to 255). 
Following the first word, each key is described (in order of priority) in blocks of 
four words. The four words specify the key’s data type, order, offset, and length, 
respectively. 


The first word of the block specifies the key’s data type. The following data types 
are accepted: 


DSC$K_DTYPE_Z 

DSC$K_DTYPE_B 

DSC$K_DTYPE_BU 

DSC$K_DTYPE_W 

DSC$K_DTYPE_WU 

DSC$K_DTYPE_L 

DSC$K_DTYPE_LU 

DSC$K_DTYPE_Q 

DSC$K_DTYPE_QU 

DSC$K_DTYPE_0 

DSC$K_DTYPE_OU 


Unspecified (uninfluenced by collating sequence) 
Byte integer (signed) 

Byte (unsigned) 

Word integer (signed) 

Word (unsigned) 

Longword integer (signed) 

Longword (unsigned) 

Quadword integer (signed) 

Quadword (unsigned) 

Octaword integer (signed) 

Octaword (unsigned) 
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DSC$K_DTYPE_F 

DSC$K_DTYPE_D 

DSC$K_DTYPE_G 

DSC$K_DTYPE_H 

DSC$K_DTYPE_T 

DSC$K_DTYPE_NU 

DSC$K_DTYPE_NL 

DSC$K_DTYPE_NLO 

DSC$K_DTYPE_NR 

DSC$K_DTYPE_NRO 

DSC$K_DTYPE_NZ 

DSC$K_DTYPE_P 


Single-precision floating 
Double-precision floating 
G-format floating 
H-format floating 

Text (may be influenced by collating sequence) 
Numeric string, unsigned 
Numeric string, left separate sign 
Numeric string, left overpunched sign 
Numeric string, right separate sign 
Numeric string, right overpunched sign 
Numeric string, zoned sign 
Packed decimal string 


The OpenVMS Programming Interfaces: Calling a System Routine describes each 
of these data types. 


The second word of the block specifies the key order: 0 for ascending order, 1 for 
descending order. The third word of the block specifies the relative offset of the 
key in the record. (Note that the first byte in the record is at position 0,) The 
fourth word of the block specifies the key length in bytes (in digits for packed 
decimal—DSC$K_DTYPE^P). 


If you do not specify the key_buffer argument, you must pass either a key 
comparison routine or use a specification file to define the key. 


Irl 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Length of the longest record that will be released for merging. The Irl argument 
is the address of a word containing the length. If the input file is on a disk, this 
argument is not required. It is required when you use the record interface. For 
VFC records, this length must include the length of the fixed-length portion of the 
record. 


options 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags that identify merge options. The options argument is the address of a 
longword bit mask whose settings determine the merge options selected. The 
following table lists and describes the bit mask values available. 


Flag Description 

SOR$M_STABLE Keeps records with equal keys in the same order as 

they appeared on input. 
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Flag 

Description 

SOR$M_EBCDIC 

Orders ASCII character keys according to EBCDIC 
collating sequence. No translation takes place. 

SOR$M_MULTI 

Orders character keys according to the multinational 
collating sequence, which collates the international 
character set. 

SOR$M_NOSIGNAL 

Returns a status code instead of signaling errors. (This 
is the default behavior.) 

SOR$M_NODUPS 

Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 

SOR$M_SEQ_CHECK 

Requests an “out of order” error return if an input file 
is not already in sequence. By default, this check is 
not done. You must request sequence checking if you 
specify an equal-key routine. 


All other bits in the longword are reserved and must be zero. 

merge_order 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Number of input streams to be merged. The merge_order argument is the 
address of a byte containing the number of files (1 through 10) to be merged. 
When you use the record interface on input, this argument is required. 

user_compare 

OpenVMS usage procedure 
type procedure value 

access function call 

mechanism by reference 

Routine that compares records to determine their merge order. The user_ 
compare argument is the address of the procedure value for this user-written 
routine. If you do not specify the key_buffer argument or if you define key 
information in a specification file, this argument is required. 

MERGE calls the comparison routine with five reference arguments—ADRSl, 
ADRS2, LENGl, LENG2, CNTX—corresponding to the addresses of the two 
records to be compared, the lengths of these two records, and the context 
longword. 

The comparison routine must return a 32-bit integer value: 

• —1 if the first record collates before the second 

• 0 if the records collate as equal 

• 1 if the first record collates after the second 

user_equal 

OpenVMS usage procedure 
type procedure value 

access function call 

mechanism by reference 
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Routine that resolves the merge order when records have duplicate keys. The 
user_equal argument is the address of the procedure value for this user-written 
routine. If you specify SOR$M_STABLE or SOR$M_NODUPS in the options 
argument, do not use this argument. 

MERGE calls the duplicate key routine with five reference arguments—ADRSl, 
ADRS2, LENGl, LENG2, CNTX—corresponding to the addresses of the two 
records that compare equally, the lengths of the two records that compare equally, 
and the context longword. 

The routine must return one of the following 32-bit condition codes. 


Code 

Description 

SOR$_DELETEl 

Delete the first record from the merge. 

SOR$_DELETE2 

Delete the second record from the merge. 

SOR$_DELBOTH 

Delete both records from the merge. 

SS$_NORMAL 

Keep both records in the merge. 

Any other failure value causes the error to be signaled or returned. Any other 
success value causes an undefined result. 

user_input 

OpenVMS usage 

procedure 

type 

procedure value 

access 

function call 

mechanism 

by reference 


Routine that releases records to the merge operation. The user_input argument 
is the address of the procedure value for this user-written routine. SOR$BEGIN_ 
MERGE and SOR$RETURN_REC call this routine until all records have been 
passed. 

This input routine must read (or construct) a record, place it in a record buffer, 
store its length in an output argument, and then return control to MERGE. 

The input routine must accept the following four arguments: 

• A descriptor of the buffer where the routine must place the record 

• A longword, passed by reference, containing the stream number from which 
to input a record (the first file is 1, the second 2, and so on) 

• A word, passed by reference, where the routine must return the actual length 
of the record 

• The context longword, passed by reference 

The input routine must also return one of the following status values: 

• SS$_NORMAL or any other success status causes the merge operation to 
continue. 

• SS$_ENDOFFILE indicates that no more records are in the file. The contents 
of the buffer are ignored. 

• Any other error status terminates the merge operation and passes the status 
value back to the caller of SOR$BEGIN_MERGE or SOR$RETURN_REC. 
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context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value that was supplied by SORT/MERGE. 


Description 

The SOR$BEGIN_MERGE routine initializes the merge process by passing 
arguments that provide the number of input streams, the key specifications, and 
any merge options. 

You must define the key by passing either the key buffer address argument 
or your own comparison routine address. (You can also define the key in a 
specification file and call the SOR$SPEC_FILE routine.) 

The SOR$BEGIN_MERGE routine initializes the merge process in the file, 
record, and mixed interfaces. For record interface on input, you must also pass 
the merge order, the input routine address, and the longest record length. For 
files not on disk, you must pass the longest record length. 

Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, you should use 
LIB$MATCH_COND if you want to check for a specific status. 


Condition Values Returned 

SS$_NORMAL 

sor$_baddtype 

SOR$_BADLENOFF 

sor$_badlogic 

SOR$_BADOCCURS 

SOR$_BADOVRLAY 

SOR$_BADPROTCL 

SOR$_BAD_KEY 

SOR$_BAD_LRL 

SOR$_BAD_MERGE 

SOR$_BAD_ORDER 

SOR$_BAD_SRL 

SOR$_BAD_TYPE 

SOR$_CDDERROR 

SOR$_CLOSEIN 


Success. 

Invalid or unsupported CDD datatype. 

Length and offset must be multiples of 8 bits. 
Internal logic error detected. 

Invalid OCCURS clause. 

Invalid overlay structure. 

Node is an invalid CDD object. 

Invalid key specification. 

Record length n greater than specified longest 
record length. 

Number of work files must be between 0 and 10. 
Merge input is out of order. 

Record length n is too short to contain keys. 
Invalid sort process specified. 

CDD error at node ' name'. 

Error closing ' file' as input. 
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SOR$_CLOSEOUT 

SOR$_COL_CHAR 

SOR$.COL_CMPLX 

SOR$_COL_PAD 

SOR$_COL_THREE 

SOR$_ENDDIAGS 

SOR$_ILLBASE, 

SOR$_ILLLITERL 

SOR$_ILLSCALE 

SOR$_INCDIGITS 

SOR$_INCNODATA 

SOR$_INCNOKEY 


Error closing ' file' as output. 

Invalid character definition. 

Collating sequence is too complex. 

Invalid pad character. 

Cannot define 3-byte collating values. 

Completed with diagnostics. 

Nondecimal base is invalid. 

Record containing symbolic literals is 
unsupported. 

Nonzero scale invalid for floating-point data item. 

Number of digits is not consistent with the type 
or length of item. 

Include specification references no data, at line 
n. 

Include specification references no keys, at line 


SOR$_IND_OVR 

SOR$_KEYAMBINC 

SOR$_KEYED 

SOR$_KEY_LEN 

SOR$_LRL_MISS 

SOR$_MISLENOFF 

SOR$_MISS_PARAM 

SOR$_MULTIDIM 

SOR$_NODUPEXC 

SOR$_NOTRECORD 

SOR$_NUM_KEY 

SOR$_OPENIN 

SOR$_OPENOUT 

SOR$_READERR 

SOR$_RTNERROR 

SOR$_SIGNCOMPQ 

SOR$_SORT_ON 

SOR$_SPCIVC 

SOR$_SPCIVD 

SOR$_SPCIVF 

SOR$_SPCIVI 

SOR$_SPCIVK 

SOR$_SPCIVP 


Indexed output file must already exist. 

Key specification is ambiguous or inconsistent. 

Mismatch between SORT/MERGE keys and 
primary file key. 

Invalid key length, key number n, length n. 
Longest record length must be specified. 

Length and offset required. 

A required subroutine argument is missing. 
Invalid multidimensional OCCURS. 

Equal-key routine and no-duplicates option 
cannot both be specified. 

Node ' name' is a name, not a record definition. 
Too many keys specified. 

Error opening 'file' as input. 

Error opening ' file' as output. 

Error reading ' file'. 

Unexpected error status from user-written 
routine. 

Absolute Date and Time data type represented in 
one-second units. 

Sort or merge routines called in incorrect order. 
Invalid collating sequence specification at line n. 
Invalid data type at line n. 

Invalid field specification at line n. 

Invalid include or omit specification at line n. 
Invalid key or data specification at line n. 

Invalid sort process at line n. 
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SOR$_SPCIVS 

SOR$_SPCIVX 

SOR$_SPCMIS 

SOR$_SPCOVR 

SOR$_SPCSIS 

SOR$_SRTIWA 

SOR$_STABLEEX 

SOR$_SYSERROR 

SOR$_UNDOPTION 

SOR$_UNSUPLEVL 

SOR$_WRITEERR 


Invalid specification at line n. 

Invalid condition specification at line n. 

Invalid merge specification at line n. 

Overridden specification at line n. 

Invalid sort specification at line n. 

Insufficient space. The specification file is too 
complex. 

Equal-key routine and stable option cannot both 
be specified. 

System service error. 

Undefined option flag was set. 

Unsupported core level for record ' name'. 

Error writing ' file'. 
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SOR$BEGIN_SORT—Begin a Sort Operation 

The SOR$BEGIN_SORT routine initializes a sort operation by opening input and 
output files and by passing the key information and any sort options. 


Format 


SOR$BEGIN_SORT [key_buffer] [,lrl] [,options] [,file_alloc] [,user_compare] 
[,user_equal] [,sort_process] [,work_files] [,context] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

key_buffer 

OpenVMS usage vector_word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Array of words describing the keys on which you plan to sort. The key^buffer 
argument is the address of an array containing the key descriptions. 

The first word of this array contains the number of keys described (up to 255). 
Following the first word, each key is described (in order of priority) in blocks of 
four words. The four words specify the key’s data type, order, offset, and length, 
respectively. 


The first word of the block specifies the data type of the key. The following data 
types are accepted: 


DSC$K_DTYPE_Z 

DSC$K_DTYPE_B 

DSC$K_DTYPE_BU 

DSC$K_DTYPE_W 

DSC$K_DTYPE_WU 

DSC$K_DTYPE_L 

DSC$K_DTYPE_LU 

DSC$K_DTYPE_Q 

DSC$K_DTYPE_QU 

DSC$K_DTYPE_0 

DSC$K_DTYPE_OU 

DSC$K_DTYPE_F 


Unspecified (uninfluenced by collating sequence) 
Byte integer (signed) 

Byte (unsigned) 

Word integer (signed) 

Word (unsigned) 

Longword integer (signed) 

Longword (unsigned) 

Quadword integer (signed) 

Quadword (unsigned) 

Octaword integer (signed) 

Octaword (unsigned) 

Single-precision floating 
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DSC$K_DTYPE_D 

DSC$K_DTYPE_G 

DSC$K_DTYPE_H 

DSC$K_DTYPE_T 

DSC$K_DTYPE_NU 

DSC$K_DTYPE_NL 

DSC$K_DTYPE_NLO 

DSC$K_DTYPE_NR 

DSC$K_DTYPE_NRO 

DSC$K_DTYPE_NZ 

DSC$K_DTYPE_P 


Double-precision floating 
G-format floating 
H-format floating 

Text (may be influenced by collating sequence) 
Numeric string, unsigned 
Numeric string, left separate sign 
Numeric string, left overpunched sign 
Numeric string, right separate sign 
Numeric string, right overpunched sign 
Numeric string, zoned sign 
Packed decimal string 


The OpenVMS Programming Interfaces: Calling a System Routine describes each 
of these data types. 


The second word of the block specifles the key order: 0 for ascending order, 1 
for descending order. The third word of the block specifies the relative offset of 
the key in the record. Note that the first byte in the record is at position 0. The 
fourth word of the block specifies the key length in bytes (in digits for packed 
decimal—DSC$K_DTYPE_P). 


The key_buffer argument specifies the address of the key buffer in the data 
area. If you do not specify this argument, you must either pass a key comparison 
routine or use a specification file to define the key. 


Irl 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Length of the longest record that will be released for sorting. The Irl argument 
is the address of a word containing the length. This argument is not required if 
the input files are on disk but is required when you use the record interface. For 
VFC records, this length must include the length of the fixed-length portion of the 
record. 


options 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags that identify sort options. The options argument is the address of a 
longword bit mask whose settings determine the merge options selected. The 
following table lists and describes the bit mask values available. 
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Flags 

Description 

SOR$M_STABLE 

Keeps records with equal keys in the same order in 
which they appeared on input. With multiple input files 
that have records that collate as equal, records from the 
first input file are placed before the records from the 
second input file, and so on. 

SOR$M_EBCDIC 

Orders ASCII character keys according to EBCDIC 
collating sequence. No translation takes place. 

SOR$M_MULTI 

Orders character keys according to the multinational 
collating sequence, which collates the international 
character set. 

SOR$M_NOSIGNAL 

Returns the condition code instead of signaling an error. 
The default is SOR$M_NOSIGNAL. 

SOR$M_NODUPS 

Omits records with duplicate keys. You cannot use this 
option if you specify your own equal-key routine. 


All other bits in the longword are reserved and must be zero. 


file_alloc 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Input file size in blocks. The file_alloc argument is the address of a longword 
containing the size. This argument is never required because, by default, SORT 
uses the allocation of the input files. If you are using the record interface or if the 
input files are not on disk, the default is 1000 blocks. 

However, you can use this optional argument to improve the efficiency of the sort 
by adjusting the amount of resources the sort process allocates. 

user_compare 

OpenVMS usage procedure 
type procedure value 

access function call 

mechanism by reference 

User-written routine that compares records to determine their sort order. The 
user_compare argument is the address of the procedure value for this user- 
written routine. If you do not specify the key_buffer argument or if you define 
key information in a specification file, this argument is required. 

SORT/MERGE calls the comparison routine with five reference arguments— 
ADRSl, ADRS2, LENGl, LENG2, CNTX—corresponding to the addresses of the 
two records to be compared, the lengths of these two records, and the context 
longword. The LENGl and LENG2 arguments are addresses that point to 16-bit 
word structures that contain the length information. 

The comparison routine must return a 32-bit integer value: 

• -1 if the first record collates before the second 

• 0 if the records collate as equal 

• 1 if the first record collates after the second 
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user_equal 

OpenVMS usage procedure 
type procedure value 

access function call 

mechanism by reference 

User-written routine that resolves the sort order when records have duplicate 
keys. The user_equal argument is the address of the procedure value for this 
user-written routine. If you specify SOR$M_STABLE or SOR$M_NODUPS in the 
options argument, do not use this argument. 

SORT/MERGE calls the duplicate key routine with five reference arguments— 
ADRSl, ADRS2, LENGl, LENG2, CNTX—corresponding to the addresses 
of the two records that compare equally, the lengths of the two records that 
compare equally, and the context longword. The LENGl and LENG2 arguments 
are addresses that point to 16-bit word structures that contain the length 
information. 

The routine must return one of the following 32-bit integer condition codes: 


Code 

Description 

SOR$_DELETEl 

SOR$_DELETE2 

SOR$_DELBOTH 

SS$_NORMAL 

Delete the first record from the sort. 

Delete the second record from the sort. 

Delete both records from the sort. 

Keep both records in the sort. 


Any other failure value causes the error to be signaled or returned. Any other 
success value causes an undefined result. 


sort_process 

OpenVMS usage 

byte_unsigned 

type 

byte (unsigned) 

access 

read only 

mechanism 

by reference 


Code indicating the type of sort process. The sort_process argument is the 
address of a byte whose value indicates whether the sort type is record, tag, 
index, or address. The default is record. If you select the record interface on 
input, you can use only a record sort process. 

To specify a byte containing the value for the type of sort process you want, enter 
one of the following: 

• SOR$GK_RECORD (record sort) 

• SOR$GK_TAG (tag sort) 

• SOR$GK_ADDRESS (address sort) 

• SOR$GK_INDEX (index sort) 


work_files 

OpenVMS usage 

type 

access 

mechanism 


byte_unsigned 
byte (unsigned) 
read only 
by reference 
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Number of work files to be used in the sorting process. The work^files argument 
is the address of a byte containing the number of work files; permissible values 
range from 0 through 10. 

By default, SORT creates two temporary work files when it needs them and 
determines their size from the size of your input files. By increasing the number 
of work files, you can reduce their individual size so that each fits into less disk 
space. You can also assign each of them to different disk-structured devices. 

context 

OpenVMS usage context 
type longword (unsigned) 

access write only 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Description 

The SOR$BEGIN_SORT routine initializes the sort process by setting up sort 
work areas and provides key specification and sort options. 

Specify the key information with the key_buffer argument, with the user_ 
compare argument, or in a specification file. If no key information is specified, 
the default (character for the entire record) is used. 

You must use the SOR$BEGIN_SORT routine to initialize the sort process for the 
file, record, and mixed interfaces. For record interface on input, you must use the 
Irl (longest record length) argument. 

Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 

Condition Values Returned 


SS$_NORMAL 

SOR$_BADLOGIC 

SOR$_BAD_KEY 

SOR$_BAD_LRL 

SOR$_BAD_MERGE 

sor$_bad_type 

SOR$_ENDDIAGS 

SOR$_INSVIRMEM 

SOR$.KEYAMBINC 

SOR$_KEY_LEN 


Success. 

Internal logic error detected. 

Invalid key specification. 

Record length n greater than specified longest 
record length. 

Number of work files must be between 0 and 10. 
Invalid sort process specified. 

Completed with diagnostics. 

Insufficient virtual memory. 

Key specification is ambiguous or inconsistent. 
Invalid key length, key number n, length n. 
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SOR$_LRL_MISS 

SOR$_NODUPEXC 

SOR$_NUM_KEY 

sor$_rtnerror 

SOR$_SORT_ON 

SOR$_STABLEEXC 

SOR$_SYSERROR 

SOR$_UNDOPTION 


Longest record length must be specified. 
Equal-key routine and no-duplicates option 
cannot both be specified. 

Too many keys specified. 

Unexpected error status from user-written 
routine. 

Sort or merge routine called in incorrect order. 
Equal-key routine and stable option cannot both 
be specified. 

System service error. 

Undefined option flag was set. 
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SOR$DTYPE—Define Data Type 

The SOR$DTYPE routine defines a key data type that is not normally supported 
by SORT/MERGE. This routine returns a key data type code that can be used 
in the key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_MERGE to 
describe special key data types (such as extended data types and NCS collating 
sequences). 


Format 


Returns 


SOR$DTYPE [context] ,dtype_code ,usage ,p1 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 

dtype_code 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Returned key data type code. The dtype^code argument is the address of a word 
into which SORT/MERGE writes the key data type code that can be used in the 
key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_MERGE. 

usage 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 
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Description 


Address of a longword containing a code that indicates the interpretation of the 
pi argument. The following table lists and describes the valid usage codes. 


Flag 

Description 

SOR$K_ROUTINE 

The pi argument should be interpreted as the 
address of the procedure value of a routine 
that SORT/MERGE will call to compare keys 
described by the dtype_code returned by the 
call to SOR$DTYPE. 

SOR$K_NCS_TABLE 

The pi argument should be interpreted as the 
address of a collating sequence identification 
returned by a call to NCS$GET_CS. SORT/MERGE 
will use this collating sequence to compare keys 
described by the dtype_code returned by the call to 
SOR$DTYPE. 


If SOR$K_ROUTINE is returned, SORT/MERGE will call this routine with five 
reference arguments—^ADRSl, ADRS2, LENGl, LENG2, CNTX—corresponding 
to the addresses of the two keys to be compared, the lengths of the two keys, and 
the context longword. 

The comparison routine must return a 32-bit integer value: 

• —1 if the first key collates before the second 

• 0 if the keys collate as equal 

• +1 if the first key collates after the second 

pi 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Address of the procedure value of a routine or the address of a collating sequence 
identification, depending on the usage argument. 


Call SOR$DTYPE to define a key data type not normally supported by SORT 
/MERGE. 

If your SORT/MERGE application needs to compare dates (for example) that are 
stored in text form and that is the only key in the records, then use the user__ 
compare argument to SOR$BEGIN_SORT or SOR$BEGIN_MERGE. However, if 
the records contain several keys besides the dates in text form, it may be easier 
to call SOR$DTYPE to allocate a key data type code that can then be used in the 
the key.buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_MERGE. 

If your SORT/MERGE application has a string key that should be collated by 
a collating sequence defined by the National Character Set (NCS) utility, the 
NCS$GET_CS routine can be used to fetch the collating sequence definition, 
and SOR$DTYPE can be called to allocate a key data type code for the collating 
sequence. This key data type code can then be used to describe keys that should 
be compared by this collating sequence. 
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Condition Values Returned 

SS$_NORMAL Success. 

SOR$_SORT_ON Sort or merge routine called in incorrect order. 
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SOR$END_SORT—End a Sort Operation 

The SOR$END_SORT routine does cleanup functions, such as closing files and 
releasing memory. 


Format 

SOR$END_SORT [context] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


ARGUMENT 


context 

OpenVMS usage context 
type longword 

access write only 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Description 

The SOR$END_SORT routine ends a sort or merge operation, either at the end 
of a successful process or between calls because of an error. If an error status is 
returned, you must call SOR$END_SORT to release all allocated resources. In 
addition, this routine can be called at any time to close files and release memory. 

The value of the optional context argument is cleared when the SOR$END_SORT 
routine completes its operation. 

Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 
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Condition Values Returned 

SS$_NORMAL 

SOR$_CLOSEIN 

SOR$_CLOSEOUT 

SOR$_ENDDIAGS 

SOR$_END_SORT 

SOR$_SYSERROR 


Success. 

Error closing ' file' as input. 

Error closing 'file' as output. 

Completed with diagnostics. 

SORT/MERGE terminated, context = ' context'. 
System service error. 
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SOR$PASS_FILES—Pass File Name 

The SOR$PASS_FILES routine passes the names of input and output files and 
output file characteristics to SORT or MERGE. 


Format 


SOR$PASS_FILES [inp_desc] [,out_desc] [,org] [,rfm] [,bks] [,bls] [,mrs] [,alq] [,fop] 
[,fsz] [.context] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

lnp_desc 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

Input file specification. The inp_desc argument is the address of a descriptor 
pointing to the file specification. In the file interface, you must call SOR$PASS_ 
FILES to pass SORT the input file specifications. For multiple input files, call 
SOR$PASS_FILES once for each input file, passing one input file specification 
descriptor each time. 

In the mixed interface, if you are using the record interface on input, pass only 
the output file specification; do not pass any input file specifications. If you are 
using the record interface on output, pass only the input file specifications; do not 
pass an output file specification or any of the optional output file arguments. 

out_desc 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

Output file specification. The out_desc argument is the address of a descriptor 
pointing to the file specification. In the file interface, when you call SOR$PASS_ 
FILES, you must pass the output file specification. Specify the output file 
specification and characteristics only once, as part of the first call, as in the 
following: 

Call SOR$PASS_FILES(Input1,Output) 

Call S0R$PASS__FILES(Input2) 

Call SOR$PASS_FILES(Inputs) 
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In the mixed interface, if you are using the record interface on input, pass only 
the output file specification; do not pass any input file specifications. If you are 
using the record interface on output, pass only the input file specifications; do not 
pass an output file specification or any of the optional output file arguments. 

org 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

File organization of the output file, if different from the input file. The org 
argument is the address of a byte whose value specifies the organization of the 
output file; permissible values include the following: 

FAB$C_SEQ 

FAB$C_REL 

FAB$C_IDX 

For the record interface on input, the default value is sequential. For the file 
interface, the default value is the file organization of the first input file for record 
or tag sort and sequential for address and index sort. 

For more information about OpenVMS RMS file organizations, see the OpenVMS 
Record Management Services Reference Manual. 

rfm 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Record format of the output file, if different from the input file. The rfm 
argument is the address of a byte whose value specifies the record format of 
the output file; permissible values include the following: 

FAB$C__FIX 

FAB$C_VAR 

FAB$C__VFC 

For the record interface on input, the default value is variable. For the file 
interface, the default value is the record format of the first input file for record or 
tag sort and fixed format for address or index sort. For the mixed interface with 
record interface on input, the default value is variable format. 

For more information about OpenVMS RMS record formats, see the OpenVMS 
Record Management Services Reference Manual. 

bks 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Bucket size of the output file, if different from the first input file. The bks 
argument is the address of a byte containing this size. Use this argument with 
relative and indexed-sequential files only. If the bucket size of the output file is 
to differ from that of the first input file, specify a byte to indicate the bucket size. 
Acceptable values are from 1 to 32. If you do not pass this argument—and the 
output file organization is the same as that of the first input file—the bucket size 
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defaults to the value of the first input file. If the file organizations differ or if the 
record interface is used on input, the default value is 1 block. 

bis 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Block size of a magnetic tape output file. The bis argument is the address 
of a word containing this size. Use this argument with magnetic tapes only. 
Permissible values range from 20 to 65,532. However, to ensure compatibility 
with non-Digital systems, ANSI standards require that the block size be less than 
or equal to 2048. 

The block size defaults to the block size of the input file magnetic tape. If the 
input file is not on magnetic tape, the output file block size defaults to the size 
used when the magnetic tape was mounted. 

mrs 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Maximum record size for the output file. The mrs argument is the address of a 
word specifying this size. Following are acceptable values for each type of file. 


File Organization 

Acceptable Value 

Sequential 

0 to 32,767 

Relative 

0 to 16,383 

Indexed sequential 

0 to 16,362 


If you omit this argument or if you specify a value of 0, SORT does not check 
maximum record size. 

If you do not specify this argument, the default is based on the output file 
organization and format, unless the organization is relative or the format is fixed. 
The longest output record length is based on the longest calculated input record 
length, the type of sort, and the record format. 

alq 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Number of preallocated output file blocks. The alq argument is the address of a 
longword specifying the number of blocks you want to preallocate to the output 
file. Acceptable values range from 1 to 4,294,967,295. 

Pass this argument if you know your output file allocation will be larger or 
smaller than that of your input files. The default value is the total allocation of 
all the input files. If the allocation cannot be obtained for any of the input files or 
if record interface is used on input, the file allocation defaults to 1000 blocks. 
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fop 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

File-handling options. The fop argument is the address of a longword whose bit 
settings determine the options selected. For a list of valid file-handling options, 
see the description of the FAB$L_FOP field in the OpenVMS Record Management 
Services Reference Manual. By default, only the DFW (deferred write) option is 
set. If your output file is indexed, you should set the CIF (create if) option. 

fsz 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Size of the fixed portion of VFC records. The fsz argument is the address of a 
byte containing this size. If you do not pass this argument, the default is the 
size of the fixed portion of the first input file. If you specify the VFC size as 0, 
OpenVMS RMS defaults the value to 2 bytes. 

context 

OpenVMS usage context 
type longword (unsigned) 

access write only 

mechanism by reference 

Value that distinguishes between multiple concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Description 

The SOR$PASS_FILES routine passes input and output file specifications to 
SORT. The SOR$PASS_FILES routine must be repeated for multiple input files. 
The output file name string and characteristics should be specified only in the 
first call to SOR$PASS_FILES. 

This routine also accepts optional arguments that specify characteristics for the 
output file. By default, the output file characteristics are the same as the first 
input file; specified output file characteristics are used to change these defaults. 

Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 
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Condition Values Returned 

SS$_NORMAL 

SOR$_DUP_OUTPUT 

SOR$_ENDDIAGS 

SOR$_INP_FILES 

SOR$_SORT_ON 

SOR$_SYSERROR 


Success. 

Output file has already been specified. 
Completed with diagnostics. 

Too many input files specified. 

Sort or merge routine called in incorrect order. 
System service error. 
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SOR$RELEASE_REC—Pass One Record to Sort 

The SOR$RELEASE_REC routine is used with the record interface to pass one 
input record to SORT or MERGE. 


Format 


SOR$RELEASE_REC desc [,context] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

desc 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

Input record buffer. The desc argument is the address of a descriptor pointing to 
the buffer containing the record to be sorted. If you use the record interface, this 
argument is required. 

context 

OpenVMS usage context 
type longword 

access modify 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Description 

Call SOR$RELEASE_REC to pass records to SORT or MERGE with the record 
interface. SOR$RELEASE_REC must be called once for each record to be sorted. 

Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 
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Condition Values Returned 


SS$_NORMAL 

Success. 

SOR$_BADLOGIC 

Internal logic error detected. 

sor$_bad_lrl 

Record length n greater than longest specified 
record length. 

SOR$_BAD_SRL 

Record length n too short to contain keys. 

SOR$_ENDDIAGS 

Completed with diagnostics. 

SOR$_EXTEND 

Unable to extend work file for needed space. 

SOR$_MISS_PARAM 

The desc argument is missing. 

SOR$_NO_WRK 

Work files required, cannot do sort in memory as 
requested. 

SOR$_OPENOUT 

Error opening ' file' as output. 

SOR$_OPERFAIL 

Error requesting operator service. 

SOR$_READERR 

Error reading ' file'. 

sor$_req_alt 

Specify alternate ' name' file (or nothing to try 
again). 

SOR$_RTNERROR 

Unexpected error status from user-written 
routine. 

SOR$_SORT_ON 

Sort or merge routines called in incorrect order. 

SOR$_SYSERROR 

System service error. 

SOR$_USE_ALT 

Using alternate file 'name'. 

SOR$_WORK_DEV 

Work file ' name' must be on random access local 
device. 
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SOR$RETURN_REC—Return One Sorted Record 

The SOR$RETURN_REC routine is used with the record interface to return one 
sorted or merged record to a program. 


Format 

SOR$RETURN_REC desc [,length] [,context] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

desc 

OpenVMS usage char_string 
type character-coded text string 

access write only 

mechanism by descriptor 

Output record buffer. The desc argument is the address of a descriptor pointing 
to the buffer that receives the sorted or merged record. 

length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Length of the output record. The length argument is the address of a word 
receiving the length of the record returned from SORT/MERGE. 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 
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Description 

Call the SOR$RETURN_REC routine to release the sorted or merged records to a 
program. Call this routine once for each record to be returned. 

SOR$RETURN_REC places the record into a record buffer that you set up in the 
program’s data area. After SORT has successfully returned all the records to the 
program, it returns the status code SS$_ENDOFFILE, which indicates that there 
are no more records to return. 

Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 

Condition Vaiues Returned 


SS$_NORMAL 

Success. 

SOR$_BADLOGIC 

Internal logic error detected. 

SOR$_ENDDIAGS 

Completed with diagnostics. 

SOR$_EXTEND 

Unable to extend work file for needed space. 

SOR$_MISS_PARAM 

A required subroutine argument is missing. 

SOR$_OPERFAIL 

Error requesting operator service. 

SOR$_READERR 

Error reading ' file'. 

SOR$_REQ_ALT 

Specify alternate 'name' file (or nothing to 
simply try again). 

SOR$_RTNERROR 

Unexpected error status from user-written 
routine. 

SOR$_SORT_ON 

Sort or merge routines called in incorrect order. 

SOR$_SYSERROR 

System service error. 

SOR$_USE_ALT 

Using alternate file 'name'. 

SOR$_WORK_DEV 

Work file ' name' must be on random access local 
device. 
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SOR$SORT_MERGE—Sort 

The SOR$SORT_MERGE routine sorts the input records. 


Format 

SO R$SO RT_M E RG E [context] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Argument 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Description 

After you have passed either the file names or the records to SORT, call the 
SOR$SORT_MERGE routine to sort the records. For file interface on input, 
the input files are opened and the records are released to the sort. For the 
record interface on input, the record must have already been released (by calls 
to SOR$RELEASE_REC). For file interface on output, the output records are 
reformatted and directed to the output file. For the record interface on output, 
SOR$RETURN_REC must be called to get the sorted records. 

Some of the return values are used with different severities depending on 
whether SORT/MERGE can recover. Thus, if you want to check for a specific 
status, you should use LIB$MATCH_COND. 
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Condition Values Returned 

SS$_NORMAL 

sor$_baddtype 

SOR$_BADLENOFF 

SOR$_BADLOGIC 

SOR$_BADOCCURS 

SOR$_BADOVRLAY 

SOR$_BADPROTCL 

sor$_bad_lrl 

SOR$_BAD_TYPE 

SOR$_CDDERROR 

SOR$_CLOSEIN 

SOR$_CLOSEOUT 

SOR$_COL_CHAR 

SOR$_COL_CMPLX 

SOR$_COL_PAD 

SOR$_COL_THREE 

SOR$_ENDDIAGS 

SOR$_EXTEND 

SOR$_ILLBASE 

SOR$_ILLLITERL 

SOR$_ILLSCALE 

SOR$_INCDIGITS 

SOR$_INCNODATA 

SOR$_INCNOKEY 

SOR$_IND_OVR 

SOR$_KEYED 

SOR$_LRL_MISS 

SOR$_MISLENOFF 

SOR$_MULTIDIM 

SOR$_NOTRECORD 

SOR$_NO_WRK 

SOR$_OPENIN 

SOR$_OPENOUT 

SOR$_OPERFAIL 


Success. 

Invalid or unsupported CDD data type. 

Length and offset must be multiples of 8 bits. 
Internal logic error detected. 

Invalid OCCURS clause. 

Invalid overlay structure. 

Node is an invalid CDD object. 

Record length n greater than longest specified 
record length. 

Invalid sort process specified. 

CDD error at node ' name'. 

Error closing ' file' as input. 

Error closing ' file' as output. 

Invalid character definition. 

Collating sequence is too complex. 

Invalid pad character. 

Cannot define 3-byte collating values. 

Completed with diagnostics. 

Unable to extend work file for needed space. 
Nondecimal base is invalid. 

Record containing symbolic literals is 
unsupported. 

Nonzero scale invalid for fioating-point data item. 

Number of digits is inconsistent with the type or 
length of item. 

Include specification references no 'data' 
keyword, at line n. 

Include specification references no 'keys' 
keyword, at line n. 

Indexed output file must already exist. 

Mismatch between SORT/MERGE keys and 
primary file key. 

Longest record length must be specified. 

Length and offset required. 

Invalid multidimensional OCCURS. 

Node 'name' is a name, not a record definition. 

Work files required, cannot do sort in memory as 
requested. 

Error opening ' file' as input. 

Error opening ' file' as output. 

Error requesting operator service. 
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SOR$_READERR 

SOR$_REQ_ALT 

sor$_rtnerror 

SOR$_SIGNCOMPQ 

SOR$_SORT_ON 

SOR$_SPCIVC 

SOR$_SPCIVD 

SOR$_SPCIVF 

SOR$_SPCIVI 

SOR$_SPCIVK 

SOR$_SPCIVP 

SOR$_SPCIVS 

SOR$_SPCIVX 

SOR$_SPCMIS 

SOR$_SPCOVR 

SOR$_SPCSIS 

SOR$_SRTIWA 

SOR$_SYSERROR 

SOR$_UNSUPLEVL 

SOR$_USE_ALT 

SOR$_WORK_DEV 

SOR$_WRITEERR 


Error reading ' file'. 

Specify alternate ' name' file (or nothing to try 
again). 

Unexpected error status from user-written 
routine. 

Absolute Date and Time data type represented in 
one-second units. 

Sort or merge routines called in incorrect order. 
Invalid collating sequence specification, at line n. 
Invalid data type, at line n. 

Invalid field specification, at line n. 

Invalid include or omit specification, at line n. 
Invalid key or data specification, at line n. 

Invalid sort process, at line n. 

Invalid specification, at line n. 

Invalid condition specification, at line n. 

Invalid merge specification, at line n. 

Overridden specification, at line n. 

Invalid sort specification, at line n. 

Insufficient space. Specification file is too 
complex. 

System service error. 

Unsupported core level for record ' name'. 

Using alternate file ' name'. 

Work file ' name' must be on random access local 
device. 

Error writing ' file'. 
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SOR$SPEC_FILE—Pass a Specification File Name 

The SOR$SPEC_FILE routine is used to pass a specification file or specification 
text to a sort or merge operation. 


Format 


SOR$SPEC_FILE [spec_file] [,spec_buffer] [,context] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

spec_file 

OpenVMS usage char_string 
type character-coded text string 

access read-only 

mechanism by descriptor 

Specification file name. The spec_file argument is the address of a descriptor 
pointing to the name of a file that contains the text of the options requested for 
the sort or merge. The specification file name string and the specification file 
buffer arguments are mutually exclusive. 

spec_buffer 

OpenVMS usage char_string 
type character-coded text string 

access read-only 

mechanism by descriptor 

Specification text buffer. The spec_buffer argument is the address of a 
descriptor pointing to a buffer containing specification text. This text has the 
same format as the text within the specification file. The specification file name 
string and the specification file buffer arguments are mutually exclusive. 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
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initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Description 

Call SOR$SPEC_FILE to pass a specification file name or a buffer with 
specification text to a sort or merge operation. Through the use of a specification 
file, you can selectively omit or include particular records from the sort or merge 
operation and specify the reformatting of the output records. (See the Sort Utility 
in the OpenVMS User's Manual for a complete description of specification files.) 

If you call the SOR$SPEC_FILE routine, you must do so before you call any other 
routines. You must pass either the spec_file or spec_buffer argument, but not 
both. 

Some of the return condition values are used with different severities, depending 
on whether SORT/MERGE can recover. Thus, if you want to check for a specific 
status, you should use LIB$MATCH_COND. 


Condition Values Returned 

SOR$_ENDDIAGS 

SOR$_SORT_ON 

SOR$_SYSERROR 


Completed with diagnostics. 

Sort or merge routine called in incorrect order. 
System service error. 
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SOR$STAT—Obtain a Statistic 

The SOR$STAT routine returns one statistic about the sort or merge operation to 
the user program. 


Format 

SOR$STAT code ,result [.context] 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Longword condition value. Most utility routines return a condition value in RO. 
Condition values that this routine can return are listed under Condition Values 
Returned. 


Arguments 

code 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

SORT/MERGE statistic code. The code argument is the address of a longword 
containing the code that identifies the statistic you want returned in the result 
argument. The following values are accepted: 


Code 

Description 

SOR$K_IDENT 

Address of ASCII string for version number 

sor$k_rec_inp 

Number of records input 

SOR$K_REC_SOR 

Records sorted 

SOR$K_REC_OUT 

Records output 

SOR$K_LRL_INP 

Longest Record Length (LRL) for input 

SOR$K_LRL_INT 

Internal LRL 

SOR$K_LRL_OUT 

LRL for output 

SOR$K_NODES 

Nodes in sort tree 

SOR$K_INI_RUNS 

Initial dispersion runs 

SOR$K_MRG_ORDER 

Maximum merge order 

SOR$K_MRG_PASSES 

Number of merge passes 

SOR$K_WRK_ALQ 

Work file allocation 

SOR$K_MBC_INP 

Multiblock count for input 

SOR$K_MBC_OUT 

Multiblock count for output 

SOR$K_MBF_INP 

Multibuffer count for input 

SOR$K_MBF_OUT 

Multibuffer count for output 
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Note that performance statistics (such as direct I/O, buffered I/O, and elapsed 
and CPU times) are not available because user-written routines may affect those 
values. However, they are available if you call LIB$GETJPL 

result 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

SORT/MERGE statistic value. The result argument is the address of a longword 
into which SORT/MERGE writes the value of the statistic identified by the code 
argument. 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Value that distinguishes between multiple, concurrent SORT/MERGE operations. 
The context argument is the address of a longword containing the context 
value. When your program makes its first call to a SORT/MERGE routine for 
a particular sort or merge operation, the context longword must equal zero. 
SORT/MERGE then stores a value in the longword to identify the operation just 
initiated. When you make subsequent routine calls for the same operation, you 
must pass the context value supplied by SORT/MERGE. 


Description 

The SOR$STAT routine returns one statistic about the sort or merge operation to 
your program. You can call the SOR$STAT routine at any time while the sort or 
merge is active. 

Some of the following condition values are used with different severities, 
depending on whether SORT/MERGE can recover. Thus, if you want to check for 
a specific status, you should use LIB$MATCH_COND. 

Condition Vaiues Returned 


SOR$_ENDDIAGS 

SOR$_MISS_PARAM 

SOR$_NYI 

SOR$_SYSERROR 


Completed with diagnostics. 

A required subroutine argument is missing. 
Functionality is not yet implemented. 
System service error. 
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A_ 

Access control list editor routines 
See ACL editor routines 
ACLEDIT$EDIT routine, ACL-3 
ACL editor routines, ACL-1 

ACL (access control list), ACL-1 
editing, ACL—3 

example of use in BLISS program, ACL-2 
manipulating, ACL-1 
options available, ACL-3 
ACLEDT$SECTION logical name, ACL-5 
ACLs (access control lists) 

See ACL editor routines 

B_ 

Binary data, compression of, DCX—1 
Buckets 

reclaiming with CONV$RECLAIM routine, 
CONV-16 

reclamation statistics, CONV-16 

C_ 

Callable interface of DECTPU routines, 
DECTPU-1 

CLI$DCL_PARSE routine, CLI-5 
CLI$DISPATCH routine, CLI-8 
CLI$GET_VALUE routine, CLI-9 
CLI$PRESENT routine, CLI-12 
CLI routines, CLI-1 

See also Command strings 
example in a FORTRAN program, CLI-2 
list of, CLI-1 
when to use, CLI-1 
Command language routines 
See CLI routines 
Command strings 
See CLI routines 
action routine, CLI—8 
checking for presence of, CLI-12 
dispatching to action routine, CLI-8 
keyword path, CLI—12 
list of label names, CLI—11 
obtaining values, CLI-9 


Command strings (cont’d) 

parsing a DCL command string, CLI-5 
positional qualifiers, CLI-13 
processing with CLI routines, CLI-1 
prompting for input, CLI-6 
symbol substitution, CLI-5 
Command tables, with CLI routines, CLI-1, 
CLI-6 

Context variables, with DCX routines, DCX-17 
CONV$CONVERT routine, CONV-6 
CONV$PASS_FILES routine, CONV-9 
CONV$PASS_OPTIONS routine, CONV-12 
CONV$RECLAIM routine, CONV-16 
CONVERT command 

list of qualifiers, CONV—13 
passing options, CONV-12, CONV-14 
setting qualifiers, CONV-12 
CONVERT routines, CONV-1 
examples, CONV-1 to CONV-5 
list of, CONV-1 

wildcard characters in, CONV-10 

p_ 

Databases 

compressing, DCX-1 
expanding, DCX-8 
Data compression 

See also DCX routines 
algorithm for submitting all data records, 
DCX-16 

analysis preceding compression, DCX-14 
size of data after compression, DCX-1 
Data Compression facility routines 
See DCX routines 
Data expansion, DCX—23 
See also DCX routines 
initializing, DCX-26 
Data Expansion facility routines 
See DCX routines 
Data records 

analysis, DCX-12 
compression, DCX-1 
conversion, CONV—1 
conversion statistics, CONV-6 
expansion, DCX-1 
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DCL command strings 
See Command strings 
DCX$ANALYZE_DATA routine, DCX-12 
DCX$ANALYZE_DONE routine, DCX-14 
DCX$ANALYZE_INIT routine, DCX-15 
DCX$COMPRESS_DATA routine, DCX-18 
DCX$COMPRESS_DONE routine, DCX-20 
DCX$COMPRESS_INIT routine, DCX-21 
DCX$EXPAND_DATA routine, DCX-23 
DCX$EXPAND_DONE routine, DCX-25 
DCX$EXPAND_INIT routine, DCX-26 
DCX$MAKE_MAP routine, DCX-28 
DCX routines, DCX-1 

examples, DCX-11 to DCX-29 
when to use, DCX-1 

with multiple streams of data records, DCX-1 
DEC Text Processing Utility routines 
See DECTPU routines 
DECTPU callable interface 
See DECTPU routines 
DECTPU routines, DECTPU-1 

bound procedure parameter value, DECTPU-3 
callable DECTPU, DECTPU-1 
error handling, DECTPU-3 
full interface, DECTPU-2, DECTPU-5 
simplified interface, DECTPU-2, 
DECTPU-4 
condition handler 

condition codes, DECTPU-4 
default, DECTPU-3 
return values, DECTPU-4 
universal symbols, DECTPU-4 
examples, DECTPU-4, DECTPU-7 to 
DECTPU-27 

shareable image, DECTPU-1, DECTPU-3 
constants, DECTPU-3 
symbols, DECTPU-3 
user-written 

FILEIO, DECTPU-70 
FILE.PARSE, DECTPU-72 
FILE.SEARCH, DECTPU-74 
HANDLER, DECTPU-77 
INITIALIZE, DECTPU-78 
requirements, DECTPU-7 
USER, DECTPU-79 

Device access, controlling through access control 
lists, ACL-1 

E_ 

EDT$EDIT routine, EDT-3 
EDT routines, EDT-1 

examples, EDT-1, EDT-2 
user-written 

FILEIO, EDT-7 
WORKIO, EDT-11 
XLATE, EDT-13 


F_ 

FDL$CREATE routine, FDL-7 
FDL$GENERATE routine, FDL-12 
FDL$PARSE routine, FDL-15 
FDL$RELEASE routine, FDL-18 
FDL (File Definition Language), FDL-1 
FDL routines, FDL—1 

See also FDL specifications 
examples, FDL-3 to FDL-6 
FDL specifications 

See also FDL routines 
creating, FDL-7 
default attributes, FDL-16 
generating, FDL-12 
in character string, FDL-2, FDL-9 
parsing, FDL-15 
semicolons as delimiters, FDL-2 
with CONVERT routines, CONV-13 
File access, controlling through access control lists, 
ACL-1 

File Definition Language routines 
See FDL routines 

File organizations, changing with CONVERT 
routines, CONV—1 
Files 

compressing, DCX-1 
expanding, DCX-8 
Prolog 3 indexed files, CONV-1 
Files, Prolog 3 indexed files, CONV-16 
File specifications, with CONVERT routines, 
CONV-10 

Full callable interface of DECTPU routines, 
DECTPU-2, DECTPU-5 

G_ 

Global sections, controlling access through access 
control lists, ACL-1 

H_ 

Headers 

library, LBR-23 
library module, LBR-22 
Help libraries, displaying text, LBR-25 

I_ 

Images, compression of, DCX-1 
Item lists 

with ACL editor routine, ACL-3 
with DECTPU routines, DECTPU-63 
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J_ 

Job controller 

function, PSM-4 

request to symbiont, SMB—5 

K_ 

Key 

See Sort/Merge utility 
Keyword paths 

obtaining values of command string keywords, 
CLI-9 

referencing command string keywords, CLI-12 

L_ 

LBR$CLOSE routine, LBR-7, LBR-8, LBR-28 
LBR$DELETE_DATA routine, LBR-16, LBR-29 
LBR$DELETE_KEY routine, LBR-16, LBR-31 
LBR$FIND routine, LBR-33 
LBR$FLUSH routine, LBR-35 
LBR$GET_HEADER routine, LBR-23, LBR-37 
LBR$GET_HELP routine, LBR-39 
LBR$GET_HISTORY routine, LBR-42 
LBR$GET_INDEX routine, LBR-26, LBR-44 
LBR$GET_RECORD routine, LBR-14, LBR-46 
LBR$INI_CONTROL routine, LBR-8, LBR-48 
LBR$INSERT_KEY routine, LBR-10, LBR-50 
LBR$LOOKUP_KEY routine, LBR-10, LBR-14, 
LBR-16, LBR-22, LBR-52 
LBR$OPEN routine, LBR-7, LBR-8, LBR-54 
LBR$OUTPUT_HELP routine, LBR-25, LBR-58 
LBR$PUT_END routine, LBR-10, LBR-62 
LBR$PUT_HISTORY routine, LBR-63 
LBR$PUT_RECORD routine, LBR-10, LBR-65 
LBR$REPLACE_KEY routine, LBR-10, LBR-67 
LBR$RET_RMSSTV routine, LBR-69 
LBR$SEARCH routine, LBR-70 
LBR$SET_INDEX routine, LBR-72 
LBR$SET_LOCATE routine, LBR-74 
LBR$SET_MODULE routine, LBR-22, LBR-75 
LBR$SET_MOVE routine, LBR-77 
LBR$_KEYNOTFND routine, LBR-10 
LBR routines, LBR-1 to LBR-18 
control index, LBR-6 
data records 

reading, LBR-46 
writing, LBR-65 

end-of-module record, writing, LBR-62 
examples, LBR-6 to LBR-18 

creating a new library, LBR-8 
deleting a module from a library, LBR-16 
to LBR-18 

inserting a module into a library, LBR—10 
to LBR-13 
header, LBR-2 


LBR routines (cont’d) 
help text 

outputting, LBR-58 
retrieving, LBR-39 
index, LBR-2 

searching, LBR-70 
introduction, LBR-5 
library 

closing, LBR-28 
creating, LBR-54 
opening, LBR-54 
shareable image, LBR-1 
structure, LBR-2 to LBR-5 
types, LBR-1 
user-developed, LBR-1 
library file, flushing, LBR-35 
library header information 
reading, LBR-37 
retrieving, LBR-37 
library index 

getting contents, LBR-44 
initializing, LBR-48 
searching for key, LBR-44 
library key, LBR-2 

creating ASCII or binary, LBR-55 

deleting, LBR-31 

finding, LBR-33 

inserting, LBR-50 

looking up, LBR-52 

replacing, LBR-67 

library update history record, retrieving, 
LBR-42 

locate mode, setting record access mode to, 
LBR-74 

module, LBR-2 

accessing with RFA, LBR-33 
deleting data records, LBR-29 
deleting header, LBR-29 
module header 

reading, LBR-75 
setting, LBR-75 
updating, LBR-75 

move mode, setting record access to, LBR-77 
RMS status value, returning, LBR-69 
setting current index number, LBR-72 
summary, LBR—6 

update history records, writing, LBR-63 
virtual memory, recovering, LBR-35 
LIB$INSERT_KEY routine, LBR-19 
LIB$SET_INDEX routine, LBR-19 
Libraries 

closing, LBR-7, LBR-8 
deleting module, LBR-16 
initializing, LBR-8 
inserting module, LBR-10 
listing index entries, LBR-26 
module header, LBR-22 
multiple indexes, LBR-19 
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Libraries (cont’d) 

multiple keys, LBR-19 
opening, LBR-7, LBR-8 
processing index entry, LBR-26 
replacing module, LBR-10 
Logical name tables, controlling access through 
access control lists, ACL-1 

M_ 

MAIL$MAILFILE_BEGIN, MAIL-32 
MAIL$MAILFILE_CLOSE, MAIL-34 
MAIL$MAILFILE_COMPRESS, MAIL-36 
MAIL$MAILFILE_END, MAIL-39 
MAIL$MAILFILE_INFO_FILE, MAIL-41 
MAIL$MAILFILE_MODIFY, MAIL-44 
MAIL$MAILFILE_OPEN, MAIL-47 
MAIL$MAILFILE_PURGE_WASTE, MAIL-50 
MAIL$MESSAGE_BEGIN, MAIL-53 
MAIL$MESSAGE_COPY, MAIL-55 
MAIL$MESSAGE_DELETE, MAIL-59 
MAIL$MESSAGE_END, MAIL-61 
MAIL$MESSAGE_GET, MAIL-63 
MAIL$MESSAGE_INFO, MAIL-68 
MAIL$MESSAGE_MODIFY, MAIL-72 
MAIL$MESSAGE_SELECT, MAIL-75 
MAIL$SEND_ABORT, MAIL-78 
MAIL$SEND_ADD_ADDRESS, MAIL-80 
MAIL$SEND_ADD_ATTRIBUTE, MAIL-82 
MAIL$SEND_ADD_BODYPART, MAIL-85 
MAIL$SEND_BEGIN, MAIL-88 
MAIL$SEND_END, MAIL-91 
MAIL$SEND_MESSAGE, MAIL-93 
MAIL$USER_BEGIN, MAIL-95 
MAIL$USER_DELETE_INFO, MAIL-98 
MAIL$USER_END, MAII^lOO 
MAIL$USER_GET_INFO, MAIL-102 
MAIL$USER_SET_INFO, MAIL-106 
Mailboxes, controlling access through access 
control lists, ACL-1 
Mail utility (MAIL), MAIL-1 
action routine, MAIL-8 

calling sequence, MAIL-8 
folder, MAIL-11, MAIL-14 
mail file, MAIL-14 
send, MAIL-16 
address list, MAIL-16 
creating, MAIL^16 
username type, MAIL—16 
bodypart, creating, MAIL-15 
condition handling, MAIL-6 
context, MAIL-3 

initiating, MAIL-4 
mail file, MAIL-9 
message, MAIL-11 
send, MAIL-14 
terminating, MAIL—4 
user profile, MAIL-17 


Mail utility (MAIL) (cont’d) 

deleted bytes threshold, MAIL-11 
disk space, reclaiming, MAIL-11 
folder, MAIL-2 

creating, MAIL-14 
deleting, MAIL-14 
folder names, displaying, MAIL-11 
item code, MAIL-7 
Boolean, MAIL-7 
input, MAIL-7, MAIL-18 
output, MAIL-7, MAIL-21 
item descriptor 

declaring, MAIL-7 
null, MAIL-7 
item list, MAJL-6 

declaring, MAIL-7 
terminating, MAIL-7 
mail file, MAJL-3 

alternate, MAIL-10 
closing, MAIL-9 
compressing, MAIL-11 
creating, MAIL-14 
default, MAIL-9 
opening, MAJL-9 
purging, MAIL-11 
specifying, MAIL-9 to MAIL-10 
wastebasket, MAIL-11 
mail file context 

initiating, MAIL—9 
terminating, MAIL-9 
message, MAJL-1 

message attributes, creating, MAIL-15 
message context 

initiating, MAIL-12 
terminating, MAIL-12 
message format, standard, MAIL-1 
message header, creating, MAIL-15 
message ID, external, MAIL-2 
messages 

attribute, MAIL—15 
copying, MAIL-13 
creating, MAIL-15 
deleting, MAIL-14 
displaying, MAIL-13 
marking, MAIL-13 
modifying, MAIL-13 
moving, MAIL-13 
printing, MAIL—13 
reading, MAIL-13 
selecting, MAIL-12 
sending, MAIL-15, MAIL-16 
null item list, MAIL—7 
programming examples, MAIL-23 
send context 

initiating, MAIL-14, MAIL-15 
terminating, MAIL-14, MAIL-15 
signaling error, MAIL-6 
thread, MAIL-5 
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Mail utility (MAIL) (cont’d) 
user context 

initiating, MAIL-17 
terminating, MAIL-17 
user profile 

flags, MAIL-18 
form, MAIL-18 
forward addressing, MAIL-18 
personal name, MAIL-18 
queue name, MAIL—18 
user profile database, MAIL-3, MAIL-17 
user profile entry, MAIL-3, MAIL-17 
adding, MAIL-18 
deleting, MAIL-18 
modifying, MAIL-18 

N_ 

NCS$COMPARE routine, NCS-7 
NCS$CONVERT routine, NCS-9 
NCS$END_CF routine, NCS-11 
NCS$END_CS routine, NCS-12 
NCS$GET_CF routine, NCS-13 
NCS$GET_CS routine, NCS-15 
NCS$RESTORE_CF routine, NCS-17 
NCS$RESTORE_CS routine, NCS-19 
NCS$SAVE_Cf routine, NCS-21 
NCS$SAVE_CS routine, NCS-23 
NCS collating sequence end routine 
See NCS$END_CS routine 
NCS compare strings routine 
See NCS$COMPARE routine 
NCS conversion function end routine 
See NCS$END_CF routine 
NCS convert string routine 
See NCS$CONVERT routine 
NCS get collating sequence routine 
See NCS$GET_CS routine 
NCS get conversion function routine 
See NCS$GET_CF routine 
NCS restore collating sequence routine 
See NCS$RESTORE_CS routine 
NCS restore conversion function routine 
See NCS$RESTORE_CF routine 
NCS routines 

C program sample, NCS-2 
FORTRAN program sample, NCS-2 
list of, NCS-1 

typical application of, NCS-2 
NCS save collating sequence routine 
See NCS$SAVE_CS routine 
NCS save conversion function routine 
See NCS$SAVE_CF routine 


O_ 

OpenVMS print symbionts 
See Symbionts 

OpenVMS RMS (Record Managment Services) 

See RMS 

Options, creating with LBR$OPEN routine, 

LBR-8 

P_ 

Print Symbiont Modification routines 
See PSM routines 
Print symbionts 
See Symbionts 
Prolog 3 indexed files 

creating with CONVERT routines, CONV-13 
reclaiming, CONV-16 
with Convert/Reclaim utility, CONV-1 
Prolog files, with CONVERT routines, CONV-13 
Prompt strings, setting with CLI$DCL_PARSE, 
CLI-7 

PSM$PRINT routine, PSM-22 
PSM$READ_ITEM_DX routine, PSM-24 
PSM$REPLACE routine, PSM-26 
PSM$REPORT routine, PSM-31 
PSM$_FUNNOTSUP routine, PSM-35 
PSM routines, PSM-1 

examples, PSM-17 to PSM-21 
USER-FORMAT-ROUTINE, PSM-34 
USER-INPUT-ROUTINE, PSM-38 
USER-OUTPUT-ROUTINE, PSM-44 

Q_ 

Queues 

execution of, PSM-3 
generic, PSM-3 

R_ 

Records 

See also Data records 
compressing, DCX-1 
expanding, DCX-8 

RMS control blocks, with FDL routines, FDL—15, 
FDL-18 

s_ 

Semicolons as delimiters, FDL—2 
Simplified callable interface 
See DECTPU routines 

SMB$CHECK_FOR_MESSAGE routine, SMB-14 
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SMB$INITIALIZE routine, SMB-15 
SMB$READ_MESSAGE routine, SMB-17 
SMB$READ_MESSAGE_ITEM routine, SMB-20 
SMB$SEND_TO_JOBCTL routine, SMB-30 
SMB routines, SMB-1 
SOR$$STAT routine, SOR-49 
SOR$BEGIN_MERGE routine, SOR-17 
SOR$BEGIN_SORT routine, SOR-24 
SOR$DTYPE routine, SOR—30 
SOR$END_SORT routine, SOR-33 
SOR$PASS_FILES routine, SOR-35 
SOR$RELEASE_REC routine, SOR—40 
SOR$RETURN_REC routine, SOR—42 
SOR$SORT_MERGE routine, SOR-44 
SOR$SPEC_FILE routine, SOR-47 
SOR routines, SOR—1 

examples, SOR-4 to SOR-16 
interface 

file, SOR-2 
record, SOR-2 
list of, SOR-1 

reentrancy using context argument, SOR-3 
Sort/Merge routines 
See SOR routines 
Sort/Merge utility (SORT/MERGE) 

See also SOR routines 
keys, SOR-1 

Symbiont/Job Controller Interface routines 
See SMB routines 
Symbionts 

See also Queues 

active stream, PSM-3 

allocating memory, SMB-4 

carriage control, processing of, PSM-11 

connecting to a device, SMB-4 

device, PSM—2 

environments, SMB—5 

function, PSM—4, SMB—2 

input, PSM-2, SMB-1 

INPSMB.EXE file, SMB-1 
input routines 

demand, PSM-6 
internal logic, PSM-5 

main format routine, PSM-13 
main input routine, PSM-10 
main output routine, PSM-14 
invoking, PSM-22 

job controller, communication with, SMB—1 
job controller requests, SMB-5 
asynchronous, SMB—6 
processing, SMB-10 
reading, SMB-10 
responding, SMB-13 
synchronous, SMB—5 
modifying, PSM-1, PSM-7, SMB-3 
format routine, PSM-12 
guidelines, PSM—8 


Symbionts 

modifying (cont’d) 

initialization routine, PSM-15 
input i v^atine, PSM-10 
integration of routines, PSM-16 
output routine, PSM-13 
restrictions, PSM-8 
multiple streams, PSM-3 
multistream, SMB-7 
multithreaded, PSM-3 
output, PSM-2, SMB-1 

PRTSMB.EXE file, SMB-1 
printer, SMB-1 
processing, PSM-1 
process-permanent file, SMB-4 
server, PSM-2, SMB-1 
single stream, PSM-3, SMB-7 
system MAXBUF parameter, PSM-7 
type, SMB-1 

user-written, PSM-1, SMB-1, SMB-3 
user-written guidelines, SMB-4 
user-written interfaces, PSM-7 
Symbiont thread, PSM-3 
SYS$OUTPUT_HELP routine, LBR-8 

T_ 

Text compression, DCX-1 
Text processing routines 
See DECTPU routines 
TPU$CLEANUP routine, DECTPU-28 
TPU$CLIPARSE routine, DECTPU-32 
TPU$CLOSE_TERMINAL routine, DECTPU-34 
TPU$CONTROL routine, DECTPU-35 
regaining control from, DECTPU-35, 
DECTPU-53 

TPU$EDIT routine, DECTPU-37 
TPU$EXECUTE_COMMAND routine, 
DECTPU-39 

TPU$EXECUTE_INIFILE routine, DECTPU-40 
TPU$FILEIO routine, DECTPU-42 
TPU$HANDLER routine, DECTPU-52 
TPU$MESSAGE routine, DECTPU-62 
TPU$PARSEINFO routine, DECTPU-63 
TPU$SPECIFY_ASYNC_ACTION routine, 
DECTPU-6, DECTPU-35, DECTPU-53, 
DECTPU-66 

TPU$TPU routine, DECTPU-68 
TPU$TRIGGER_ASYNC_ACTION routine, 
DECTPU-6, DECTPU-35, DECTPU-53, 
DECTPU-69 


Index-6 




u_ 

User-written DECTPU routines 
See DECTPU routines 

w_ 

Wildcard characters, with CONVERT routines, 
CONV-10 


Index-7 



NOTES 


NOTES 



NOTES 



NOTES 





NOTES 



NOTES 


6 




NOTES 


7 


NOTES 



NOTES 



NOTES 




How to Order Additional Documentation 


Technical Support 

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825) 
and press 2 for technical assistance. 


Electronic Orders 

If you wish to place an order through your account at the Electronic Store, dial 800-234-1998, using a 
modem set to 2400- or 9600-baud. You must be using a VT terminal or terminal emulator set at 8 bits, no 
parity If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825) and ask for an 
Electronic Store specialist. 


Telephone and Direct Mail Orders 


From 


Call 


Write 


U.S.A. 


Puerto Rico 


Canada 


International 


Internal Orders^ 
(for software 
documentation) 


Internal Orders 
(for hardware 
documentation) 


DEC direct 

Phone: 800-DIGITAL 
(800-344-4825) 

FAX: (603) 884-5597 

Phone: (809) 781-0505 
FAX: (809) 749-8377 


Phone: 800-267-6215 
FAX: (613) 592-1946 


DTN: 241-3023 
(508) 874-3023 


DTN: 234-4325 
(508) 351-4325 
FAX: (508) 351-4467 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, NH 03061 


Digital Equipment Caribbean, Inc. 

3 Digital Plaza, 1st Street 

Suite 200 

Metro Office Park 

San Juan, Puerto Rico 00920 

Digital Equipment of Canada Ltd. 
100 Herzberg Road 
Kanata, Ontario, Canada K2K 2A6 
Attn: DECdirect Sales 

Local Digital subsidiary or 
approved distributor 

Software Supply Business (SSB) 
Digital Equipment Corporation 
1 Digital Drive 
Westminster, MA 01473 

Publishing & Circulation Services 
Digital Equipment Corporation 
NR02-2 

444 Whitney Street 
Northboro, MA 01532 


^Call to request an Internal Software Order Form (EN-01740-07). 
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